Nehanda CLI
An agentic terminal REPL and single-process engine for governed AI deep research and software development. Every turn, tool call, phase transition, and permission check is stored in a local SQLite database you own.
Architecture
Nehanda CLI is a layered system with five distinct layers. Every component shown below is documented in the pages listed under Nehanda CLI in the sidebar.
The architecture has five layers:
| Layer | What it does | Documented in |
|---|---|---|
| REPL / Ink TUI | Command parsing, permission gates, display rendering | REPL Reference, Permissions |
| Engine Core | Turn loop (runUserTurn), SDLC state machine, tool orchestration, [TOOL_CALL] rescue path |
Engine & Turn Loop, SDLC Workflow, Tool Calling |
| Tool Layer | 21 built-in tools, 4 safety checkers, MCP client for external tools | Built-in Tools, MCP Integration |
| Provider Layer | OpenAI-compatible client abstraction, multi-provider switching | Providers |
| Persistence Layer | Local SQLite database (14 tables, WAL mode, FTS5) | Database |
Cross-cutting concerns are documented separately:
- Configuration — Settings files, merge strategy,
/configcommands - Hooks — Event-driven hook system for file changes, tool use, and phase transitions
- Pipe Mode — Headless execution,
--eval,--transition, and automation
Key Features
In-Process Engine
Executes turns directly inside the process via runUserTurn, eliminating separate server daemons or background HTTP relays. The engine runs a deterministic loop: prompt → API call → tool execution → response, all within a single Node.js process.
Deterministic SDLC Workflow
Enforces a 6-phase state machine (idle → explore → planning → implement → test → verify → done) to prevent unapproved code changes, hallucinated test passes, or unverified implementations. Each phase has its own system prompt, tool mask, and human gate.
Permission Gate
Every tool call passes through the permission gate before execution. Five permission modes (default, bypassPermissions, dontAsk, acceptEdits, plan) control whether tools are auto-allowed, auto-denied, or require human confirmation. Permissions are phase-aware: implement and test phases auto-allow execution tools since the plan was already approved.
21 Built-in Tools
File operations (Read, Write, Edit), shell execution (Bash), discovery (Glob, Grep), web access (WebFetch, WebSearch), notebook editing, git worktrees, subagent spawning, MCP integration, and more. Tools are filtered by SDLC phase — mutating tools are masked during explore and planning.
Multi-Provider Switching
Seamlessly switch between Nehanda 27B, local LM Studio, Ollama instances, Anthropic Claude, Zhipu GLM, or any OpenAI-compatible API using /model. The provider layer auto-detects capabilities (e.g., Ollama tool support) and falls back to manual tool injection when needed.
Dynamic Tool Rescue ([TOOL_CALL])
For endpoints that strip OpenAI tool schemas (like the Nehanda vLLM proxy), the engine injects tool schemas into system prompts using [TOOL_CALL] delimiters, parses them from model output, and executes them locally — bypassing vLLM’s --tool-call-parser stop-token interception entirely.
Complete Audit Trail
Every conversation turn, tool call, phase transition, permission decision, and hook invocation is stored in a local SQLite database at ~/.config/nehanda/ona-session.db. You own this data — no cloud dependency for persistence.
Quick Start
git clone https://github.com/AsobaCloud/nehanda-cli.git
cd nehanda-cli
npm install
npm start
See the Getting Started page for the full setup guide including provider configuration.
License
AGPL-3.0. This project is a fork of aimee (AGPL-3.0). See NOTICE for third-party attributions.