Getting Started

niuma_code is a supplementary tool for Claude Code. Download niuma.exe, configure your API key, and launch — no installation needed.

What You'll Learn

How to download and run niuma.exe
How to configure your API provider
How to launch niuma_code for the first time
Basic navigation and core commands

Prerequisites

Requirement	Details
OS	Windows 10 or later
Disk	~50 MB free space
API Key	Anthropic API key (or compatible provider)

niuma_code is distributed as a single portable executable — no Python, no Node.js, no npm required.

Step 1: Download

Download the latest release:

# Direct download link
# https://niumacode.oss-cn-beijing.aliyuncs.com/releases/niuma.exe

Save niuma.exe anywhere on your machine (e.g., D:\tools\niuma.exe).

Step 2: Configure API Key

Create the config file at ~/.niuma/settings.json:

# Navigate to user home
cd %USERPROFILE%
mkdir .niuma 2>nul

Create settings.json:

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

Field	Description
`base_url`	API endpoint URL
`api_key`	Your authentication key
`options`	List of available model names

Step 3: Launch

niuma.exe

You should see the niuma_code logo and an interactive prompt:

  (__) ^__^   niuma code
  (nu) (ma)   claude-sonnet-4-6
  (__)  \/    D:\your\project
   /|   ||

Type your first question and press Enter to start a conversation.

Step 4: Basic Navigation

Action	How
Send a message	Type and press Enter
Cancel generation	Press `Esc`
Switch models	Type `/model`
View commands	Type `/help`
Exit	Type `/quit`

First Conversation

Try sending a simple message to verify everything works:

> Hello! Can you help me understand this project?

niuma_code will:

Connect to your configured API
Start an autonomous tool-use loop
Read files, explore code, and respond

Configuration Options

Multiple Providers

Add multiple API endpoints to switch between models:

{
    "factories": [
        {
            "base_url": "https://api.anthropic.com",
            "api_key": "sk-ant-key1",
            "options": ["claude-sonnet-4-6", "claude-opus-4-8"]
        },
        {
            "base_url": "https://api.openai.com",
            "api_key": "sk-openai-key2",
            "options": ["gpt-4o"]
        }
    ]
}

Use /model to open the model selection overlay and switch between them on the fly.

Advanced Configuration

Below is a complete settings.json reference. All fields are optional — only factories is required to start.

{
    "factories": [
        {
            "base_url": "https://api.anthropic.com",
            "api_key": "your-api-key-here",
            "options": ["claude-sonnet-4-6", "claude-opus-4-8"]
        }
    ],
    "llm": {
        "default_model": "claude-sonnet-4-6",
        "default_effort": "high",
        "max_contexts": 5,
        "resume_latest_context": false,
        "options": [
            {"claude-sonnet-4-6": ["low", "medium", "high"]},
            {"claude-opus-4-8": ["low", "medium", "high"]}
        ],
        "thinking_budget_low": "0",
        "thinking_budget_medium": "0",
        "thinking_budget_high": "10000",
        "thinking_budget_max": "20000"
    },
    "env": {
        "persona_name": "niuma",
        "model_background": "claude-haiku-4-5",
        "temperature_zero": "true",
        "debug_seed": "",
        "trace_enabled": "false",
        "debug_usage": "false",
        "api_timeout": "30",
        "api_round_max": "120",
        "api_stall_max_retries": "2",
        "permission_mode": "auto",
        "allowed_tools": ""
    },
    "memory_palace": {
        "enable_v9": true,
        "llm_enabled": false,
        "base_url": "https://api.anthropic.com",
        "api_key": "your-api-key-here",
        "model": "claude-haiku-4-5"
    },
    "memory_quality": {
        "min_store_importance": 0.4,
        "min_recall_score": 0.35,
        "dedup_threshold": 0.3
    },
    "compact": {
        "inline_trigger": 0.8,
        "inline_keep_ratio": 0.4,
        "idle_trigger": 0.5,
        "idle_keep_ratio": 0.4,
        "max_summary_tokens": 4096,
        "auto_recall_clear": false
    }
}

`factories` — API Provider

Field	Type	Description
`base_url`	string	API endpoint URL
`api_key`	string	Authentication key
`options`	string[]	Available model names for this provider

`llm` — Model & Context Behavior

Field	Type	Default	Description
`default_model`	string	`claude-sonnet-4-6`	Model used on startup
`default_effort`	string	`high`	Default reasoning effort (`low` / `medium` / `high`)
`max_contexts`	int	`5`	Maximum parallel contexts before LRU eviction
`resume_latest_context`	bool	`false`	`true`: restore last active context on restart; `false`: start fresh
`options`	array	—	Per-model effort level mapping
`thinking_budget_*`	string	—	Token budget for thinking at each effort level

`env` — Runtime Settings

Field	Type	Default	Description
`persona_name`	string	`niuma`	Assistant display name
`model_background`	string	`claude-haiku-4-5`	Model used for background tasks (recall scoring, summaries)
`temperature_zero`	string	`true`	Force temperature=0 for deterministic output
`api_timeout`	string	`30`	HTTP request timeout in seconds
`api_round_max`	string	`120`	Maximum conversation rounds per session
`api_stall_max_retries`	string	`2`	Retries on stalled API response
`permission_mode`	string	`auto`	Tool permission mode (`auto` / `ask` / `allow`)
`allowed_tools`	string	`""`	Comma-separated tool whitelist (empty = all allowed)

`memory_palace` — Memory System

Field	Type	Default	Description
`enable_v9`	bool	`true`	Enable memory recall on session start
`llm_enabled`	bool	`false`	Use LLM for memory analysis (requires additional API key)
`base_url`	string	—	LLM endpoint for memory analysis (if enabled)
`api_key`	string	—	LLM API key for memory analysis (if enabled)
`model`	string	`claude-haiku-4-5`	Model used for memory analysis

`memory_quality` — Memory Quality Thresholds

Field	Type	Default	Description
`min_store_importance`	float	`0.4`	Minimum importance score to store a memory
`min_recall_score`	float	`0.35`	Minimum score to include in recall results
`dedup_threshold`	float	`0.3`	Semantic similarity threshold for deduplication

`compact` — Context Compaction

Field	Type	Default	Description
`inline_trigger`	float	`0.8`	Trigger inline compaction at this context fill ratio
`inline_keep_ratio`	float	`0.4`	Fraction of context preserved after inline compaction
`idle_trigger`	float	`0.5`	Trigger idle compaction after this idle duration ratio
`idle_keep_ratio`	float	`0.4`	Fraction of context preserved after idle compaction
`max_summary_tokens`	int	`4096`	Maximum tokens for generated summary
`auto_recall_clear`	bool	`false`	Auto-clear recall results after compaction

Next Steps

harness — Autonomous Chat — Understand the default autonomous mode
loop — Engineered Orchestration — Goal-driven task execution
Multi-Context Parallelism — Work on multiple tasks simultaneously