nimbie-shell 0.0.3.dev17

Lightweight agent loop and context manager (standalone)

nimbie

nimbie is a terminal-first coding assistant shell.

This repository now contains two main parts:

• nimbie (root package): REPL/UI, command tools, shell execution flow, session UX
• oturn (sub-package): standalone async orchestration/runtime core for agent turns

Repository Layout

• src/nimbie: CLI app and terminal UI
• oturn/src/oturn: reusable orchestration package
• chron: chronml package used for message/config templating
• flash: shell runtime bridge and executor components

Requirements

• Python >=3.11
• uv (recommended)

Install (Root CLI)

uv sync
uv pip install -e .

Run:

nimbie --help
uv run nimbie --help

Install (oturn only)

If you only want the orchestration package:

cd oturn
uv sync
uv pip install -e .

Build

Root package:

uv build

oturn package:

cd oturn
uv build

Config

The CLI loads config from (first match wins by runtime path logic):

• ~/.nimbie/config.py
• ~/.nimbie/config.json
• ~/.openclaw/openclaw.json
• .nimbie_config.py
• .nimbie_config.json

Provider profiles may also opt into fake Claude Code request headers for Anthropic-compatible APIs:

CONFIG = {
    "models": {
        "providers": {
            "anthropic_like": {
                "api": "anthropic-messages",
                "baseUrl": "https://example.invalid/anthropic",
                "models": [{"id": "claude-test"}],
            }
        }
    },
    "auth": {
        "profiles": {
            "demo": {
                "provider": "anthropic_like",
                "apiKey": "sk-...",
                "apiKeyHeader": "authorization_bearer",
                "fakeClaudeCode": True,
            }
        }
    },
}

When enabled, nimbie adds Claude Code style headers such as x-app, User-Agent, and X-Claude-Code-Session-Id. You can override the generated values with:

• NIMBIE_CLAUDE_CODE_SESSION_ID
• NIMBIE_CLAUDE_CODE_USER_AGENT
• CLAUDE_CODE_CONTAINER_ID
• CLAUDE_CODE_REMOTE_SESSION_ID
• CLAUDE_AGENT_SDK_CLIENT_APP
• CLAUDE_CODE_ADDITIONAL_PROTECTION

You can also force query params onto the provider base URL:

"extraQueryParams": {
    "beta": "true"
}

This is merged onto api_base before the LiteLLM request is sent.

Debug Environment Variables

For shell-tool debugging, nimbie also reads these environment variables:

• NIMBIE_SHELL_DEBUG=1 Emit lifecycle/debug lines for execute_shell_command.
• NIMBIE_SHELL_STREAM_QUEUE_MAX=1024 Override the max in-memory streamed shell event queue size.
• NIMBIE_SHELL_DEBUG_EVENT_SAMPLE_EVERY=1000 When debug is enabled, print a sample log every N streamed events/drops.
• NIMBIE_SHELL_THREAD_JOIN_MS=50 Override the polling/join interval used while waiting for streamed shell execution.

Example:

NIMBIE_SHELL_DEBUG=1 \
NIMBIE_SHELL_STREAM_QUEUE_MAX=256 \
NIMBIE_SHELL_DEBUG_EVENT_SAMPLE_EVERY=200 \
nimbie --ui-version v2 --debug-tool-calls --debug-loop

Session and History

• Session artifacts are stored under .nimbie/ in the workspace/global locations used by CLI.
• The UI supports continue/list/export workflows via CLI flags and REPL commands.

Notes

• Flash runtime is expected for shell parsing/execution flow.
• oturn does not use global auto tool registry; tools are injected explicitly at runtime.