CodeAgent CLI
A Python terminal coding agent in the manner of Claude Code: reads the repository, edits files, runs commands, with memory, sub-agents and MCP
- 1,026 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- The agent itself runs shell commands and writes files, with approval needed only for dangerous commands and writes outside the allowlist
- It talks to the model provider and to web pages, and the API key is stored in `~/.codeAgent/settings.json` in plain text
- Hooks, cron jobs, background sub-agents and MCP connections run with the user's rights
Install
Manual install
git clone https://github.com/Harvil1/codeAgent.git
cd codeAgent
uv sync
uv run python main.pyRequires Python 3.11 or newer and `uv`. The API key is set through the provider's environment variable or in `~/.codeAgent/settings.json`. To continue the last session: `uv run python main.py -c`.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The agent itself runs shell commands and writes files, with approval needed only for dangerous commands and writes outside the allowlist
- It talks to the model provider and to web pages, and the API key is stored in `~/.codeAgent/settings.json` in plain text
- Hooks, cron jobs, background sub-agents and MCP connections run with the user's rights
This is third-party code. Review the repository files before installing.
What it does
CodeAgent works in the terminal as an AI programming assistant. You write a task in plain language, and the agent reads code, edits files, runs commands and searches the web until it is done. The main loop assembles messages, compresses context, refreshes the toolset, calls the model and dispatches tool calls, and when the model stops asking for tools it wraps up. The author says everything from the interface to the main loop was written by hand and the code carries detailed comments in Chinese. The model connects over the OpenAI or Anthropic protocol, with DeepSeek as the default. A cheaper auxiliary model can be set up beside it for compression, retrieval and memory extraction. Dangerous commands and file writes outside the allowlist go to an approval panel: allow once, always allow or deny. External tools connect through the project's `.mcp.json`, and the first connection needs approval. Memory is kept in `MEMORY.md` and a JSONL journal. Sub-agents run synchronously or in the background in isolated worktrees, and there is a team mode with a coordinator, a workflow engine with resume, cron jobs, hooks and session rollback with `/rewind`. A self-learning pipeline watches the conversation and saves repeatable moves as new skills.
Who it is for. For developers who want an open terminal agent in the spirit of Claude Code with DeepSeek, OpenAI, Anthropic or OpenRouter models, and for those studying how an agent is built from carefully commented code.
Good fit when
- You need a terminal agent for Windows that works in cmd, Windows Terminal and PowerShell
- You want to work with DeepSeek or another OpenAI-protocol model instead of Claude Code
- Dangerous commands and writes outside the allowlist should go to approval with the decision remembered
- To study how an agent is built you want readable code: tools, context compression, memory, sub-agents
- You need sub-agents in separate worktrees, scheduled jobs and rollback of a session to a checkpoint
Not a fit when
- You need strong command isolation on any system: the `bwrap` sandbox exists only on Linux
- You need a ready installer: the project installs by cloning and running `uv sync`, and needs Python 3.11 or newer and `uv`
- You need documentation in Russian: the description and code comments are in Chinese, and the English version is in `README.en.md`
Example request
Read this repository, find why the tests fail, fix it and run the tests again, and show me commands outside the allowlist for approvalLimitations
- The project is developed and checked mainly on Windows. Linux runs, including the optional `bwrap` sandbox, and macOS by the author's own assessment should work in theory but is not fully verified. Under `git-bash` (mintty) the agent restarts itself through `winpty`.
- The API key is read from the `DEEPSEEK_API_KEY`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `OPENROUTER_API_KEY` or `ZHIPUAI_API_KEY` variables or from `models.<name>.api_key` in `~/.codeAgent/settings.json`, where the key sits in plain text.
- All data lives in `~/.codeAgent/`: settings, sessions, memory, skills, plugins and logs rotated at 5 MB across three files. The directory is changed with the `CODEAGENT_HOME` variable.
- Before editing the author recommends running `scripts/verify.py` with more than 60 checks and `ruff check`.
How to disable. Close the session and delete the cloned project folder. To erase settings, sessions, memory and logs, delete the whole `~/.codeAgent/` directory, which is a full reset. MCP connections from the project's `.mcp.json` are removed by editing that file.
FAQ
Do I have to use DeepSeek?
No, DeepSeek is the default, but any server speaking the OpenAI or Anthropic protocol works. `/model` walks you through setup: provider, key and endpoint, or you edit `settings.json`.
What happens to a dangerous command?
Destructive commands and file writes outside the allowlist go to an approval panel with three options: allow once, always allow or deny. Decisions are remembered across sessions by command or by prefix, and constructs like `$()` and process substitution raise the approval level.
How does the agent guard against leaking keys?
A secret scanner keeps API keys out of files and memory. SSRF protection and web content isolation limit what the agent takes from the network. There are also deletion path red lines and self-protection against modification.
What is self-learning?
A pipeline watches the course of a conversation and saves repeatable moves as new skills, observing with a heuristic or an auxiliary model. Skills live in `~/.codeAgent/skills/` and plugins install with `/plugin`.
How do I continue an interrupted session?
Starting with the `-c` flag brings back the latest session, and `/resume`, `/sessions` and `/new` manage the rest. `/rewind` rolls the work back to a chosen checkpoint.
How does context compression work?
There are four levels, from light trimming to deep summarization, plus summaries of tool batches and time-based cleanup of old results. Temporary messages are inserted so as not to break the cacheable request prefix.
Discussion
No questions or reviews yet.
Related
CLI toolsA terminal coding agent tuned for the deepseek-v4 model: deep thinking, reasoning effort control, Agent Skills and MCP
MiniCode is a compact TypeScript terminal coding agent like Claude Code: tool loop, TUI, skills, MCP and sub-agents, built for study and tinkering
A coding agent for the terminal and desktop: it does not count "done" without tests or a diff and works with DeepSeek, GLM, Kimi, Claude, Codex and Gemini
A local sandbox for AI agents: they run code and actions in an isolated container exposed over MCP
A Rust SDK for coding agents and the ready-made abstract CLI: REPL, 34 tools, MCP, graph memory, Anthropic and OpenAI, JSON output for CI
Charm's terminal coding agent: any model, switching models mid-session, LSP, MCP and Agent Skills
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Repository stars | Main difference |
|---|---|---|---|
| CodeAgent (this entry) | no | 1,026 | |
| OpenCode | no | 220,388 | an open agent for the terminal and desktop with build and plan modes |
| Aider | no | 49,706 | pair programming with a codebase map, git autocommits, linting and tests after edits |
| CoreCoder | no | 1,864 | a teaching terminal coding agent in Python |
README in short
The repository holds an `agent/` package with dozens of modules (model client, context compression, memory, permissions, hooks, sub-agents, workflow engine, command injection guards), built-in sub-agent definitions `coordinator`, `explore`, `plan` and `verification`, the `scripts/verify.py` check script, `main.py` and descriptions in Chinese and English. The main page shows the features, a quick start, a command table, where data lives, an architecture overview and answers to common questions.