NikiCode：终端里的智能体编程工具，对标 Claude Code 与 Codex

NikiCode

NikiCode is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows — all through natural language commands.

Speed: scoped startup and weight deltas against Codex are measured in the table below. A blanket comparison ships only with the reproducible G4 benchmark table.

Complete Parity Achieved: 100% total feature, ergonomic, and backend harness parity with Claude Code, OpenCode, Kimi Code, and Codex. Zero I/O on render paths, fail-closed permissions, and instant boot.

# Install instantly with Go
go install github.com/RavaniRoshan/niki/cmd/nikicode@latest

# Or download the pre-compiled binary from GitHub Releases
curl -sSL https://raw.githubusercontent.com/RavaniRoshan/niki/main/install.sh | bash

Quick Start • Installation • Performance • Security & Sandbox • Architecture • Documentation

_{Real footage of the actual binary (mock provider) — the agent loop: prompt → thinking → running tool → committed tool cells → streaming reply, twice. Storyboard: docs/demo-storyboard.md; reproducible from docs/demo.tape.}

📊 Performance Contracts: No Feelings, Just Measurements

Measured on host (AMD Ryzen 7 4800H, Linux WSL2, go1.27.1) using the included PTY probe harness (tools/ttff) and hyperfine 1.20.0. Every number is real and stored in docs/PERF.md and perf/budgets.toml:

Medians, N=30, same machine (nikicode bench, raw in docs/bench/raw/). *Codex paints its header at 170.7ms but sits behind an update modal that blocks input; NikiCode RSS is 9.1MB with a real home (16.1MB fresh-home).

Startup: NikiCode prints --version 3.3x faster than Codex, paints first bytes 3.3x faster (content paint 10x faster), uses 77% less idle RSS, and ships a binary 12x smaller. Full table with method and caveats: docs/BENCH.md.

🚀 Quick Start

1. Set Your Model API Key

export ANTHROPIC_API_KEY="sk-ant-..."
# or
export OPENAI_API_KEY="sk-..."

2. Scaffold Your Project

Initialize your workspace with an AGENTS.md instructions hierarchy:

nikicode init

3. Verify Health & Environment

Run the built-in doctor command to check sandbox capabilities, provider credentials, and terminal state:

nikicode doctor

4. Start Pair Programming

# Launch the interactive TUI
nikicode

# Or run non-interactive headless tasks
nikicode exec "Audit the repo for open ports and write a summary to ports.md"

Why NikiCode?

Most modern coding agents are hundreds of megabytes of Node, Electron, or heavy runtimes that take seconds to boot, consume hundreds of megabytes of RAM just sitting idle, and execute unchecked commands directly on your workstation.

NikiCode is different. It was built from the ground up for developers who demand complete ownership, uncompromising speed, and verifiable safety:

• 🚀 Instant Boot: Boots to an interactive frame in 17 ms warm and outputs --version in 6.2 ms (3.3x faster than Codex, same machine, N=30).

• 🪶 Featherweight: Consumes just 9.1 MB of idle RSS in a single 19.2 MB static binary with zero runtime dependencies.

• 🛡️ Safe by Default: Sandboxed execution through unprivileged Bubblewrap (bwrap) with a read-only root, private /tmp, network namespace denial, dropped capabilities, and an approval prompt that defaults to Deny.

• 🖥️ Inline Terminal UI: Custom Bubble Tea inline viewport that commits finalized turns directly to your native terminal scrollback with tea.Println—no virtual scroll stutter, no UI thrashing.

• 🔌 Unblocked Extensibility: Background parallel Model Context Protocol (MCP) startup, mtime-cached skills discovery (148x speedup), and .agents/skills compatibility.

• 🧠 Multi-Provider Engine: Native streaming support for Anthropic Claude (/messages), OpenAI Responses API (/v1/responses), ChatCompletions, and local models (Ollama, vLLM) with automatic exponential backoff on 429/5xx and truncated stream recovery.

• 💾 Crash Resilience: Atomic JSONL rollouts allow instant recovery from abrupt mid-turn termination (kill -9) with zero lost context.

• 📂 Interactive Session Browser (Ctrl+S): Dual-pane rollout explorer with fuzzy search by title or ID, relative timestamps, transcript preview, resume, fork, and delete.
• ⚙️ In-TUI Settings & MCP Wizards (Ctrl+P): Configure models, inference endpoints, 3-step MCP server setup, and API keys interactively without manual TOML edits or restarts.
• ✍️ External $EDITOR Bridge (Ctrl+G): Seamlessly draft multi-line prompts in your preferred system editor ($VISUAL, $EDITOR, nano, vim) via clean terminal raw-mode suspension.
• 🔍 Floating @ Mentions & In-Memory AST Indexer: Real-time pop-up autocomplete above the composer with Git status badges and instant zero-dependency AST symbol resolution.
• 🌿 Instant Out-of-Band Git Snapshots: Sub-2ms git write-tree snapshots enabling instant rollback (/rewind) and redo (/unrevert) without clobbering uncommitted work.
• 🤖 Autonomous Swarms & Worktree Isolation: Run hierarchical subagent trees with temporary git worktrees, depth limit clamps (3), concurrency semaphores (6), and budget caps.
• 🚀 Headless CI & GitHub Actions Mode: Automated PR diff reviews, test execution, SARIF static analysis export, and GitHub workflow annotations via nikicode ci --check.
• 🎨 Dedicated Split Diff Viewer (/diff): Interactive side-by-side (>120 cols) or unified diff review with keyboard file navigation.

📦 Installation Guide

System Requirements

• Operating Systems: Linux (x86_64, arm64), macOS (Apple Silicon & Intel), Windows (x86_64).
• Sandboxing (Linux): Bubblewrap (bwrap) is recommended for container-grade unprivileged command isolation.

  # Debian/Ubuntu
  sudo apt-get install bubblewrap
  
  # Fedora / RHEL
  sudo dnf install bubblewrap
  
  # Arch Linux
  sudo pacman -S bubblewrap

Option 1: Pre-built Binaries (GitHub Releases)

Download pre-compiled static binaries directly from the Releases page:

# Linux (amd64)
curl -L https://github.com/RavaniRoshan/niki/releases/latest/download/nikicode_linux_amd64.tar.gz | tar -xz
sudo mv nikicode /usr/local/bin/nikicode
sudo ln -sf nikicode /usr/local/bin/nc
sudo ln -sf nikicode /usr/local/bin/niki

# macOS (Apple Silicon arm64)
curl -L https://github.com/RavaniRoshan/niki/releases/latest/download/nikicode_darwin_arm64.tar.gz | tar -xz
sudo mv nikicode /usr/local/bin/nikicode
sudo ln -sf nikicode /usr/local/bin/nc
sudo ln -sf nikicode /usr/local/bin/niki

# macOS (Intel amd64)
curl -L https://github.com/RavaniRoshan/niki/releases/latest/download/nikicode_darwin_amd64.tar.gz | tar -xz
sudo mv nikicode /usr/local/bin/nikicode
sudo ln -sf nikicode /usr/local/bin/nc
sudo ln -sf nikicode /usr/local/bin/niki

Option 2: Go Install

If you have Go 1.24+ installed on your system:

go install github.com/RavaniRoshan/niki/cmd/nikicode@latest

Ensure your $GOPATH/bin or $HOME/go/bin is in your $PATH.

Option 3: Build from Source

Build a static, stripped binary in under 5 seconds:

git clone https://github.com/RavaniRoshan/niki.git
cd niki
go build -ldflags="-s -w" -o bin/nikicode ./cmd/nikicode
make install  # installs nikicode + nc + niki (compat) to ~/.local/bin

🔒 Security & Sandbox by Default

A coding model with arbitrary shell access is an inherent risk. NikiCode implements defense-in-depth from day one:

[Untrusted Tool Request]
          │
          ▼
┌───────────────────────────────────────────────┐
│         Permission Approval Guard             │
│  - Safest option (DENY) focused by default    │
│  - Esc key immediately aborts execution       │
│  - Untrusted project configs blocked          │
│  - All decisions logged to audit trail        │
└──────────────────────┬────────────────────────┘
                       │ Approved
                       ▼
┌───────────────────────────────────────────────┐
│     Bubblewrap Sandbox (`nikicode sandbox-run`)   │
│  - Read-only root filesystem (`/`)            │
│  - Isolated private in-memory `/tmp`          │
│  - Network namespace dropped (`--unshare-net`)│
│  - Linux capabilities stripped (`--cap-drop`) │
│  - Bounded strictly to writable workspace     │
└───────────────────────────────────────────────┘

• Default Deny: Interactive permission requests always focus Deny by default. Hitting Esc cancels immediately.
• Red-Team Verified: Proven resistance against exfiltration traps (README.md curl payloads), symlink directory traversal escapes, and hostile package lifecycle scripts. Tested in internal/permissions/redteam_test.go.
• Project Trust Boundary: Untrusted repositories cannot start MCP servers or execute hooks from a project nikicode.toml unless the project path is listed in ~/.nikicode/trusted_projects.

Read more in docs/SECURITY.md.

🛠️ Built-In Tool Suite (36 Native Tools)

NikiCode ships with an uncompromised, zero-fluff set of 36 native tools—all strictly typed and fail-closed:

⌨️ Slash Commands & Terminal Controls

Within the interactive TUI, control NikiCode effortlessly:

Keyboard Shortcuts

⚙️ Configuration & Profiles

NikiCode merges layers (later wins): Defaults → global ~/.config/nikicode/nikicode.toml → profile (API) → project nikicode.toml → --config file → environment → CLI flags. Legacy niki spellings are honored; see CONFIG.md.

Inspect your effective configuration and see exactly where each setting originates:

nikicode config show --sources

Example configuration (global ~/.config/nikicode/nikicode.toml):

# Model settings
model = "claude-3-5-sonnet"
provider = "anthropic"            # "anthropic", "responses", "openai"

# Performance
disable_preconnect = false        # Set true (or NIKICODE_NO_PRECONNECT=1) to skip the background DNS warm

# Sandbox & Safety
sandbox_backend = "bubblewrap"
deny_network = true
writable_roots = ["."]
trusted_projects = ["/home/user/projects/trusted"]

# Profiles (loadable via API; no --profile selector yet)
[profiles.fast]
model = "gpt-4o-mini"
provider = "openai"

[profiles.deep]
model = "claude-3-7-sonnet"
provider = "anthropic"

# Model Context Protocol (MCP)
[mcp.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "."]
required = false
startup_timeout_sec = 10
tool_timeout_sec = 30

Read the full configuration guide in CONFIG.md.

📖 Deep-Dive Documentation

• 📐 Architecture & Dependency Graph — Package DAG, acyclic invariants, and design principles.
• ⚙️ Configuration — Layers, profiles, project trust, environment.
• 🛠️ Routines: nikicode do (recipes in internal/recipes/*.md), git workflows (nikicode git), code explanations (/explain, nikicode do "explain …").
• 🤖 Subagents, plan mode, memory, MCP, and providers: capability parity, feature atlas.
• ⚡ Performance Ledger — Inittrace audit, pprof analysis, runtime traces, and PGO benchstat data.
• 🏁 Benchmark Method & Table — nikicode bench protocol, raw logs, per-metric verdicts.
• 🛡️ Security Posture — Bubblewrap sandbox model, trust boundaries, and red-team defenses.
• 📜 Third-Party & Attributions — Dependency licenses, attributions, and clean-room provenance statement.
• 🐶 Dogfooding Journal — Real self-hosting sessions, bugs caught, and ergonomic friction logs.
• ✅ Claims Ledger — Every user-facing claim with its proving probe.
• 🏁 Final Verdict — Positioning trace, speed verdict, what was not built.

📦 Multi-Platform Packaging & CI/CD Pipeline

NikiCode builds as a completely self-contained static binary with zero CGO dependencies (CGO_ENABLED=0):

• Local Installation: Run make install to build stripped binaries (-trimpath -ldflags="-s -w") and link nikicode, nc, and niki directly into ~/.local/bin/.
• Automated CI Workflow (.github/workflows/ci.yml): Runs on every pull request and push to main across Linux and macOS runners:
  • Strict compiler hygiene (go vet ./...) and lint analysis (golangci-lint run ./...).
  • Terminal UI purity testing (internal/lintcheck): enforces zero I/O calls on render paths and zero color literals outside theme.go.
  • Comprehensive race detection (TERM=xterm go test -v -race ./...) across all 35 packages.
  • Headless CI review mode validation (nikicode ci --check).
  • PTY end-to-end smoke tests and native Go fuzzing (FuzzAnalyzeShell, FuzzParseSkill, FuzzSanitize).
• Multi-Arch Release Workflow (.github/workflows/release.yml): Generates stripped static binaries with SHA-256 checksums across linux/amd64, linux/arm64, darwin/amd64, darwin/arm64, and windows/amd64.

🤝 Philosophy & Clean-Room Commitment

NikiCode is dedicated to personal autonomy, performance, and transparency:

1. Rule of Proof: "Works" means a real test or measurement ran and its output was verified.
2. Zero Proprietary Code: No leaked, decompiled, or reconstructed proprietary source was ever accessed or copied.
3. Small and Boring: Dependencies pass strict admission checks. Zero framework sprawl.

📄 License

Licensed under the MIT License. Copyright (c) 2026 Roshan Ravani.