nano-claude-code

nano-claude-code is a small, teaching-oriented coding agent built with Bun and TypeScript. It keeps the core loop explicit: load settings, assemble context, call a model, execute tool calls, persist the session, and render the result in either print mode or an interactive REPL.

Development

Install dependencies:

bun install

Run the test suite:

bun test

Build the CLI bundle:

bun run build

Run the full verification command used in this repo:

bun run check

Usage

The CLI reads configuration from command-line flags, an optional JSON config file, and environment variables.

Required environment:

export OPENAI_API_KEY=your-api-key

Optional environment:

export OPENAI_BASE_URL=https://api.openai.com/v1

Interactive REPL:

bun run src/entrypoints/cli.ts

Print mode for a single prompt:

bun run src/entrypoints/cli.ts -p "inspect the repository"

Common flags:

-p, --print, --prompt  Run a single prompt and exit
--debug                Enable debug settings override
--cwd <path>           Run the agent against a different working directory
--model <name>         Override the configured model name
--config <path>        Load settings from a JSON config file

REPL commands:

/clear  Clear the terminal
/exit   Exit the REPL

Example config file:

{
  "model": "gpt-4.1",
  "debug": false,
  "maxTurns": 8,
  "apiBaseUrl": "https://api.openai.com/v1",
  "apiKey": "optional-if-env-is-set"
}

Repository-safe template:

cp config.example.json config.json

Publishing Safely

• Keep real credentials in config.json or environment variables only.
• config.json is ignored by git and should never be committed.
• Use config.example.json as the shareable template.
• Before pushing, verify staged files with git diff --cached --name-only and git diff --cached.
• If a real API key was ever committed, rotate it immediately and rewrite git history before publishing.

Architecture

• src/entrypoints/cli.ts: command-line parsing, settings resolution, print mode, and REPL loop.
• src/core/QueryEngine.ts: session orchestration around the model client, tool execution, and persistence.
• src/core/query.ts: normalized assistant/tool loop that drives multi-turn execution.
• src/context/*: system prompt, project context, and memory context assembly for each model request.
• src/tools/*: built-in tool definitions, registry, validation, and execution.
• src/services/api/*: model-client abstraction and the OpenAI-compatible provider.
• src/services/memory/*: file-backed session and memory storage.

The CLI entrypoint is intentionally thin. Most behavior lives below it so the REPL and print mode can share the same QueryEngine and provider stack.