CloseCode reads a task, decides what to do, runs a tool, looks at the result, and repeats — the same loop as OpenCode or Claude Code, built from scratch on LangGraph (agent loop), LangChain (tool + model abstraction), and OpenRouter (model access). It runs entirely in your terminal, in a full-screen TUI or a classic line-based mode, and every action it takes on your files or shell goes through a sandboxed harness with permission prompts.

Why

Most people can't pip install openai and get an agent — the hard part isn't calling a model, it's the loop around it: binding the right tools per mode, confirming risky actions, persisting sessions, and stopping the model from doing something destructive. CloseCode is that scaffolding, built openly, with open models via OpenRouter instead of a closed API.

Features

• Full-screen TUI (Textual) or a classic line-based REPL — same agent loop underneath, switchable with --no-tui
• Sandboxed execution — file and shell operations are confined to a working directory; path traversal (../../etc/passwd, absolute paths, Windows drive prefixes) is blocked at the harness level, not just by convention
• Plan / Build modes — Plan mode literally never binds write/edit/bash tools to the model, so it can explore and propose a plan with no possibility of a side effect
• Guardrails — four layers: input-scope filtering, destructive-command blocking (rm -rf /, fork bombs, curl | sh), malicious-write scanning, and output redaction
• Persistent sessions — SQLite-backed conversation history; /resume, /sessions, --continue
• Todo tracking — the agent maintains a visible task list for multi-step work (todo_write / todo_read)
• Code-aware search — dedicated grep/glob tools (not raw shell), sandboxed and available even in Plan mode since they're read-only
• Git tools via MCP — status, diff, log, commit, branches, through mcp-server-git
• Any OpenRouter model — free-tier models by default; switch with /model, browse with /models
• Per-user config — your API key and default model persist in ~/.closecode/config.json (0600 permissions), independent of which directory you launch from

Install

pipx install closecode-ai
closecode

From source, right now:

git clone https://github.com/omgite333/CLOSECODE.git
cd CLOSECODE
pip install -e .
closecode

pipx is recommended over pip for the packaged version since it installs CLI tools into an isolated environment and puts them straight on your PATH.

Quick start

1. Get a free API key at openrouter.ai/settings/keys

2. Run closecode — on first launch it prompts for the key (input hidden) and offers to save it to ~/.closecode/config.json so you're not asked again

3. Type a task:

   > find every place we call the old auth API and list the files
   

How it works

 user input
     │
     ▼
 ┌──────────┐   binds tools for current mode     ┌───────────────┐
 │  agent   │ ───────────────────────────────▶ │ LangGraph loop│
 │ (llm.py) │                                   │  (agent.py)   │
 └──────────┘                                    └──────┬────────┘
                                                        │ tool call
                                                        ▼
                                              ┌───────────────────────┐
                                              │      Harness          │
                                              │ sandboxed fs + shell  │──▶ guardrails.py
                                              └───────────────────────┘     (blocks/scans)
                                                        │ result
                                                        ▼
                                              ┌──────────────────────┐
                                              │  Renderer interface  │
                                              │ (render.py)          │
                                              └──────┬──────────┬────┘
                                                     ▼          ▼
                                              tui.py (Textual)  ui.py (classic)

A single Renderer interface (render.py) decouples the agent loop from presentation, so the Textual TUI and the classic REPL are two implementations of the same contract rather than two copies of the agent logic.

Modes

Plan mode isn't a prompt instruction the model can ignore — the write/edit/bash tools are never bound to the model in the first place.

Tools

Commands

/plan, /build         switch modes
/models [filter]      list OpenRouter models (free-tier first)
/model <id|number>    switch model
/key                  update your OpenRouter API key
/sessions             list saved conversations
/resume <id>          switch to a saved session
/delete <id>          delete a saved session
/usage                token usage for this session
/clear                start a new session
/help                 show all commands

Configuration

All settings are environment variables (.env, or exported in your shell) — see .env.example for the full list. Key ones:

Safety model

This is layered defense, not a single mechanism:

1. Input scope — off-topic requests are redirected; clearly malicious requests (keyloggers, phishing kits, account-hacking) are refused before reaching the model
2. Command blocking — destructive shell commands are blocked before execution, even with auto-approve on
3. Write scanning — file writes/edits are scanned for malware indicators before they're applied
4. Output redaction — flagged content is scrubbed from conversation history
5. Sandboxed paths — every file operation resolves through the harness, which refuses to write outside the configured working directory regardless of how the path is phrased

These are conservative heuristics layered on top of the sandbox and per-action permission prompts — not a formal guarantee. Shell commands currently run on the host inside a path-restricted directory, not inside a container; see Roadmap.

A note on model choice

Tool-calling reliability varies a lot across open models — this is the single biggest factor in how well the agent performs. Frontier closed models are heavily trained for reliable tool use; open models are improving but inconsistent. Roughly in order of reliability, worth trying via /model:

• qwen/qwen-2.5-coder-32b-instruct — code-specialized, solid tool use, free tier available
• qwen/qwen-2.5-72b-instruct — strong, reliable, paid
• meta-llama/llama-3.1-70b-instruct — strong, reliable, paid
• meta-llama/llama-3.1-8b-instruct — fastest/cheapest, least reliable

If a smaller model frequently fails to call tools or hallucinates arguments, that's a known gap between open and closed models on agentic tasks, not a bug here. Switching models is the first thing to try before changing anything else.

Roadmap

• Test suite + CI (guardrails, sandbox path resolution, todo-store invariants)
• Docker-based sandbox for shell execution, not just path restriction
• Client/server split — build_graph() behind FastAPI/WebSocket, thin streaming client
• PyPI release + prebuilt binaries (PyInstaller) for no-Python-required installs
• Homebrew tap

Contributing

Issues and PRs welcome. If you're adding a tool, follow the pattern in tools.py / search.py: bind state via a module-level bind_*() function, keep it sandboxed to the harness root, and add it to the Plan-mode allowlist only if it's genuinely read-only.

License

MIT — see LICENSE.