FAQ — Frequently Asked Questions

Answers to the most common questions about niuma_code.

General

What is niuma_code?

niuma_code is a supplementary CLI tool for Claude Code. It provides persistent memory, parallel contexts, multi-provider routing, and code knowledge graphs — features that extend Claude Code's capabilities for serious development work.

Key difference: niuma_code accumulates experience across sessions via its memory system, so the AI learns your codebase over time.

What is the difference between niuma_code and Claude Code?

Aspect niuma_code Claude Code
Memory Persistent cross-session memory (SQLite) No persistent memory
Multi-context N parallel contexts with LRU eviction Single context
Providers Multiple API endpoints with model routing Single provider
Knowledge graph Built-in tree-sitter code graph External tools only
TUI Full-screen terminal UI with mouse support Standard CLI
Cost BYO API key (same Anthropic billing) Subscription required

niuma_code is designed for developers who want more control over their AI coding workflow.

Is niuma_code free?

Yes. niuma_code is open-source under the MIT License. You only pay for your own API usage (Anthropic or compatible providers).

What programming languages are supported?

niuma_code itself is written in Python. The code knowledge graph supports Python, JavaScript, TypeScript, Go, Java, Rust, Ruby, and PHP for symbol indexing.

The tool works with any language in your codebase — it reads, writes, and searches all file types.

Configuration

Do I need to install Python?

No. niuma_code is distributed as a single portable executable (niuma.exe). No Python, Node.js, or npm installation is required.

How do I configure my API key?

Create ~/.niuma/settings.json with your provider credentials:

{
    "factories": [
        {
            "base_url": "https://api.anthropic.com",
            "api_key": "sk-ant-your-key-here",
            "options": ["claude-sonnet-4-6"]
        }
    ]
}

See the Getting Started tutorial for a complete walkthrough.

How do I switch between models?

Type /model to open the model selection overlay. Models are listed from all configured providers, and you can switch instantly.

Where is my data stored?

All data is stored locally in ~/.niuma/projects/niuma_code/:

Directory Contents
session/ Conversation history, task states, execution traces
memory/ SQLite memory database
ide/ IDE draft files

Nothing is sent to external servers except your API calls to your configured LLM provider.

Usage Tips

When should I use /loop vs harness mode?

Use harness mode when... Use /loop when...
Task is exploratory or fuzzy Task has clear, verifiable steps
You want the AI to figure things out You want structured execution with checkpoints
Quick edits or fixes Complex multi-step workflows
Single-goal work Parallel independent tasks

Example harness prompt: "Fix the KeyError in auth.py when email is missing"

Example /loop prompt: "Add unit tests for the UserService class: 1) create test file, 2) test CRUD operations, 3) run pytest to verify"

How do I manage permissions?

Type /permission auto (default, auto-allow tools) or /permission manual (ask before each tool use).

To permanently allow a tool: /permission allow execute_bash

Settings persist to rules/permissions.json.

How do I use IDE orchestration mode?

  1. Type /ide new <script-name> to create a new orchestration script
  2. Write Python code with llm_call() / llm_confirm() / llm_judge() functions
  3. Press F5 to preview (static analysis), F6 to execute

The IDE mode runs Python natively with injected LLM bridge functions, allowing you to orchestrate complex multi-step workflows with human-in-the-loop confirmation.

How do I cancel a running operation?

Press Esc or Ctrl+C at any time to cancel:

Related Tutorials