🤖 Codeagent

A terminal-native AI coding agent — describe a goal, watch it build.

Features • Quick Start • Usage • Configuration • Documentation • Contributing

codeagent is a terminal-native AI coding agent, distributed as an npm package. Describe a goal in plain language — codeagent reads your project, plans, edits files, runs commands, and iterates until the task is done, asking for confirmation before anything destructive.

Unlike chat-based coding assistants that only print code blocks for you to manually copy, codeagent acts directly on your codebase: reading, writing, editing files, searching across your project, and executing shell commands — all driven by an LLM that decides which tools to call and when.

The project's direction is a self-hosted, provider-agnostic agent with the same shape as Claude Code: an agent loop, a growing tool set, Hooks, Skills, fine-grained permission rules, and Plan Mode all shipped — a Plugin system is what's still ahead. See Roadmap below for what's shipped versus what's planned.

Features

Capability	Description
🧠 Agentic, not just chat	Calls tools directly (read/write/edit files, search code, run shell commands) instead of printing diffs for you to paste.
🛡️ Safe by default	Every destructive action requires confirmation unless you explicitly pass `--yolo`, refined by fine-grained allow/deny rules and a `--plan` read-only mode — see `docs/20`.
🔄 Resumable sessions	Kill the process and pick up exactly where you left off — no context lost.
↩️ Undo built in	Revert the agent's most recent file changes without touching git.
🔌 Six providers today	Anthropic, OpenRouter, Mistral, Groq, Cerebras, and Ollama — switch with `--provider` and `--model`.
🧙 Guided setup	`codeagent setup` walks through provider, API key, and model selection.
📜 Scriptable	One-shot mode with proper exit codes — works in CI as well as interactively.
🧩 Extensible by design	Add new tools, providers, or config options without touching the core loop.
✅ Skills	102 discoverable `SKILL.md` capabilities ship with the repo, read on demand — see Roadmap. Plugins still planned.

Roadmap

Where codeagent is headed, and honestly, what's real today versus what's still design/in-progress. A full feature-by-feature audit against current Claude Code lives in docs/16; day-to-day phase planning lives in PLAN.md (not part of the published package).

Area	Status	Notes
Core agent loop, 6 tools, safety/undo/sessions	✅ Shipped	`docs/02`–`docs/08`.
Six provider adapters	✅ Shipped	`docs/06`. Switch with `codeagent use <provider>`, or override per-run with `--provider`/`--model`.
Setup wizard, persisted config, first-run auto-detection	✅ Shipped	`codeagent setup` remembers your choices in `~/.codeagentrc` and auto-runs on a fresh install. `codeagent providers` / `codeagent use` manage multiple configured providers; history carries over across a switch — see `docs/18`.
API key in OS keychain	✅ Shipped	Read and write now — `codeagent setup` can save a key to the keychain and it's actually read back at boot (`docs/18`). Also fixed a real shell-injection risk in how keys were passed to `security`/`pass`/`cmdkey`.
Admin system prompt	✅ Shipped (v1)	`codeagent system-prompt set "<text>"` — global, priority-layered over project context, doesn't touch the Safety Layer or Hooks (`docs/18`).
Hooks (lifecycle events: pre/post tool use, session start/end)	✅ Shipped (v1)	Shell-command hooks only; `PreToolUse` can block, `PostToolUse` can add context. Project-scoped (`.codeagent/hooks.json`) only — see `docs/17` and `codeagent hooks`.
Skills (discoverable `SKILL.md` folders, progressive disclosure)	✅ Shipped	Project-scoped (`.codeagent/skills/`) only for now. 102 skills ship with the repo, spanning languages, testing, git workflow, code quality, APIs, databases, security, DevOps, frontend, docs, performance, debugging, concurrency, architecture, cloud, mobile, and more. Real, measured cost: the index alone is ~6,500 tokens on every turn at this scale — see `docs/19`. `allowed-tools` is parsed but still not enforced against skills specifically. See `codeagent skills`.
Fine-grained permission rules & Plan Mode	✅ Shipped (v1)	Evolves the existing confirm/`--yolo` safety layer rather than replacing it — deny always wins over allow; `--plan` makes destructive tools describe instead of execute, for the whole session. Both verified against real tools and real files, not just unit tests. No in-REPL toggle yet (waiting on Slash Commands). See `docs/20`, `codeagent permissions`.
Subagents	🚧 Planned	Touches `orchestrator.js` directly, so per `docs/11` this needs a design pass, not a routine PR. Also reverses `docs/01`'s current "not a multi-agent framework" non-goal — that doc will be updated when this ships.
MCP client (connect external tool servers)	🚧 Planned	Separate from the LLM provider adapters above — this is a new tool source, not a new provider.
Plugins (bundle Skills+Subagents+Hooks+MCP, install from GitHub/npm/local path)	🚧 Planned	Deliberately last — in real Claude Code a plugin is a packaging format over the four items above, so building it first would ship an empty container.
Interactive config manager, usage/cost tracking	🚧 Planned	Lower priority than the above; see `PLAN.md` Phase 9.

Enterprise/hosted infrastructure (Bedrock/Vertex/Foundry routing, gateways, admin console, Slack/VS Code/JetBrains first-party extensions, hosted cloud execution, agent teams, remote control, computer use) is an explicit non-goal for this project — see docs/16 for the reasoning.

Quick Start

Prerequisites

Node.js 18+ — required for native fetch and ESM support.
Anthropic API key — set as the ANTHROPIC_API_KEY environment variable.

Install

npm install -g codeagent

Or run without installing:

npx codeagent

Setup

export ANTHROPIC_API_KEY="sk-ant-..."

Security note: Your API key is never stored in config files, logs, or session data. It is read from the environment variable at runtime and used only in the provider layer's HTTP requests.

Your first session

cd your-project
codeagent

That starts an interactive REPL in your current directory. Describe what you want:

> Add input validation to the signup form and write a test for it

The agent will:

Read the relevant files to understand your codebase.
Show you a diff before writing anything.
Wait for your confirmation before each destructive action.
Iterate until the task is complete.

Usage

Commands

codeagent                        Start interactive session in current directory
codeagent "do X"                 One-shot: run a single request, print result, exit
codeagent --resume <id>          Resume a specific saved session
codeagent --resume last          Resume the most recent session for this project
codeagent --yolo                 Skip destructive-action confirmations for this run
codeagent --plan                 Plan mode: describe destructive actions instead of performing them
codeagent --model <name>         Override the configured model for this run
codeagent --provider <name>      Override the configured provider for this run
codeagent setup                  Interactive first-time setup wizard (provider, key, model)
codeagent models [provider]      List available models for a provider (--details for pricing/context)
codeagent mistral-models         List Mistral models live from your API key
codeagent undo                   Revert the most recent destructive change
codeagent undo <ref>             Revert a specific recorded change
codeagent sessions               List saved sessions for this project
codeagent config                 Print the fully resolved config (API key redacted)
codeagent hooks                  List hooks configured for this project (.codeagent/hooks.json)
codeagent skills                  List skills discovered in .codeagent/skills/
codeagent permissions             List permission rules configured for this project (.codeagent/permissions.json)
codeagent providers               List every configured provider, which is active, and its key source
codeagent use <provider> [model]  Switch the active provider/model (persists; history carries over)
codeagent system-prompt [show|set <text>|clear]   Manage your global admin system prompt

Setup wizard: codeagent setup walks you through it once — provider, key, model — and remembers it in ~/.codeagentrc. Run it again anytime to add another provider, switch your default, or reconfigure a key; on a completely fresh install, just running codeagent triggers it automatically before your first command.

Interactive REPL

Streaming output by default — text renders as it arrives from the provider.
Tool calls are rendered distinctly from the model's own text (e.g., → Reading src/index.js).
Destructive-action confirmations show the actual diff, not just a description.
Errors are rendered clearly and distinctly from normal output.

One-shot mode

codeagent --yolo "run the migration"

Runs a single turn non-interactively and exits with:

Exit code 0 on success.
Non-zero exit code on failure (limit hit, unrecoverable error, or destructive action needing confirmation without a TTY).

This makes codeagent suitable for scripting and CI pipelines.

Session management

codeagent sessions              # List all saved sessions
codeagent --resume last         # Resume the most recent session
codeagent --resume abc123       # Resume a specific session by ID

Sessions are persisted after every turn (not just on clean exit), so a killed process loses at most one in-flight turn.

Undo

codeagent undo                  # Revert the most recent destructive change
codeagent undo abc123           # Revert a specific recorded change

The undo system tracks every destructive action with before/after content — it's a fast safety net, not a replacement for git.

Architecture

codeagent is built on a clean, layered architecture where each component has exactly one responsibility:

┌─────────────────────────────────────────────┐
│                 CLI / REPL                    │
│        (arg parsing, terminal I/O)           │
└──────────────────────┬───────────────────────┘
                       │
                ┌──────▼────────┐
                │  Agent Core    │
                │ (orchestrator) │
                └───┬──────┬─────┘
                    │      │
        ┌───────────▼──┐ ┌─▼────────────┐
        │ Provider Layer│ │ Tool Registry │
        │   (LLM API)   │ │  (tool list)  │
        └───────────────┘ └──┬────────────┘
                              │
                    ┌─────────▼──────────┐
                    │  Individual Tools   │
                    │ (read, write, bash) │
                    └─────────┬───────────┘
                              │
                    ┌─────────▼──────────┐
                    │  Safety/Confirmation│
                    │       Layer         │
                    └─────────────────────┘

        ┌────────────────────────────────────┐
        │  Cross-cutting: Session Store,      │
        │  Config, Logger, Context Manager    │
        └────────────────────────────────────┘

Layer	Responsibility
CLI / REPL	Argument parsing, terminal I/O, output rendering
Agent Core	The loop: send → tool_use → execute → tool_result → repeat
Provider Layer	Translating abstract "send messages, get response" into a specific API's wire format
Tool Registry	Holding the list of available tools and their JSON schemas
Individual Tools	Doing one file/shell operation each, returning a structured result
Safety Layer	Classifying and gating destructive actions
Session Store	Persisting conversation + file-change history to disk
Config	Resolving layered settings into one final config object

Data flow for a single turn

User types a request in the REPL.
Agent Core appends it to the session's message list.
Agent Core calls the Provider Layer with messages + tool schemas.
Provider Layer returns text or tool_use blocks.
For each tool_use: Agent Core looks up the tool, passes through the Safety Layer, then executes.
Tool result is appended; loop returns to step 3.
When the model returns plain text with no tool calls, the turn ends and the session is persisted.

Configuration

Settings resolve in this order (highest precedence first):

CLI flags → Project config (.codeagent/config.json) → Global config (~/.codeagentrc) → Built-in defaults

You don't need any config file to get started — everything works out of the box once ANTHROPIC_API_KEY is set.

Key configuration fields

Field	Type	Default	Description
`provider`	`"anthropic" \| "openrouter" \| "mistral" \| "groq" \| "cerebras" \| "ollama"`	`"anthropic"`	LLM provider to use
`model`	`string`	`"claude-sonnet-4-6"`	Model name
`maxIterationsPerTurn`	`number`	`25`	Max tool-use iterations per user turn
`yolo`	`boolean`	`false`	Skip destructive-action confirmations
`allowedWritePaths`	`string[]`	`["."]`	Paths the agent is allowed to write to
`planningEnabled`	`boolean`	`false`	Enable explicit task decomposition
`ollamaBaseUrl`	`string`	`"http://localhost:11434"`	Only read by the `ollama` provider

Supported providers

codeagent ships six provider adapters, all behind the same Provider interface (doc 06) — switching between them is just --provider <name> (and usually --model <name> too), no code change.

Provider	`provider` value	API key env var	Notes
Anthropic	`anthropic`	`ANTHROPIC_API_KEY`	Default
OpenRouter	`openrouter`	`OPENROUTER_API_KEY`	Gateway to many models, including `:free`-tagged ones
Mistral	`mistral`	`MISTRAL_API_KEY`	console.mistral.ai
Groq	`groq`	`GROQ_API_KEY`	console.groq.com — very fast inference, free tier
Cerebras	`cerebras`	`CEREBRAS_API_KEY`	cloud.cerebras.ai — very fast inference, free tier
Ollama	`ollama`	none (local)	Runs fully offline against a local Ollama server; set `ollamaBaseUrl` to point elsewhere

Example:

export GROQ_API_KEY="gsk_..."
codeagent --provider groq --model llama-3.3-70b-versatile

# No API key needed — talks to a local Ollama server
codeagent --provider ollama --model llama3.1

API key

Read from the environment variable named in apiKeyEnvVar (default ANTHROPIC_API_KEY).
Never stored directly in a config file.
If the env var isn't set, boot fails immediately with a clear instruction.

Safety

Destructive actions (writing files, editing files, running shell commands) always show you exactly what's about to happen and wait for confirmation — this isn't configurable per-tool.

Mechanism	Description
Confirmation prompts	Every destructive call shows the actual diff before proceeding
`--yolo` flag	Bypass confirmations for unattended/CI runs (explicit, per-invocation)
Audit logging	Every bypassed confirmation is still logged with tool, input, and timestamp
Path traversal protection	Tools refuse to write outside the project root unless explicitly configured
Undo capability	All file changes are recorded and revertible, even under `--yolo`

If you want the agent to run unattended (e.g., in a script or CI), pass --yolo explicitly. Every bypassed confirmation is still logged, and file changes are still undoable even under --yolo.

Tools

codeagent ships with six core tools that give the agent full control over your project:

Tool	Destructive	Purpose
`read_file`	No	Read file contents for code analysis
`write_file`	Yes	Create or overwrite files
`edit_file`	Yes	Make targeted find-and-replace edits
`list_dir`	No	Explore project structure
`search_code`	No	Regex search across the codebase
`run_bash`	Yes	Execute shell commands

Adding a new tool is an additive change — create one file in src/tools/ and register it. No core files need to change.

Documentation

Full architecture and design docs live in docs/:

Doc	Covers
00 — Index	Start here — map of the entire doc set
01 — Overview	Vision, goals, target users, non-goals
02 — System Architecture	Module map, data flow, layer responsibilities
03 — Package Structure	Folder layout, package.json, module boundaries
04 — Agent Core & Loop	The orchestrator loop, limits, error handling
05 — Tools	Every tool's schema, contract, and behavior
06 — Provider Layer	LLM abstraction, Anthropic adapter, retry logic
07 — Safety & Permissions	Destructive-op gating, confirmation flow, `--yolo`
08 — Context & Session Management	Context window handling, persistence, undo
09 — Configuration	Layered config system, schema, env vars
10 — CLI & UX	Commands, flags, REPL behavior, output formatting
11 — Extensibility & Plugins	Adding tools/providers without touching core
12 — Testing & QA	Test strategy per module, CI gates
13 — Deployment, Publishing & Versioning	npm publish pipeline, semver, changelog
14 — Support, Maintenance & Roadmap	Issue triage, support channels, roadmap
15 — Security & Privacy	API key handling, sandboxing, telemetry stance
16 — Claude Code Parity Audit	Feature-by-feature audit vs. current Claude Code; what's in scope, what isn't, and why
17 — Hooks	Lifecycle event system — PreToolUse/PostToolUse/SessionStart/SessionEnd
18 — Provider Management & Admin Prompt	Multi-provider config, persisted setup, shared history across providers, admin system prompt
19 — Skills	`SKILL.md` discovery, progressive disclosure, `.codeagent/skills/`
20 — Permission Rules & Plan Mode	Fine-grained allow/deny rules, `--plan` read-only execution mode, precedence with Hooks and Safety

Extensibility

codeagent is designed so that adding capabilities is additive — a new file plus a one-line registration — rather than requiring changes to the orchestrator, provider layer, or safety layer.

Extension	What to do
New tool	Create `src/tools/myTool.js` matching the tool shape, add one line to `src/tools/index.js`
New provider	Create `src/providers/myProvider.js` implementing the `Provider` interface, add one `case` to the factory
New config option	Add the field to `ConfigSchema` in `src/config/schema.js` with a sensible default

See doc 11 — Extensibility & Plugins for the full guide.

Contributing

We welcome contributions! Here's how to get started:

Read the docs — especially doc 11 (Extensibility) and doc 14 (Support & Maintenance).
Most contributions are additive — new tools, new providers, new config options don't require touching the core loop.
Tests are required — every new tool/provider needs tests per the patterns in doc 12.
PRs touching orchestrator.js, base.js, or policy.js need extra scrutiny — these are the core contracts.

# Setup
git clone https://github.com/khandev1211-cpu/Codeagent.git
cd codeagent
npm install

# Run tests
npm test

# Lint
npm run lint

Security

Please report security issues privately rather than opening a public issue. See doc 15 — Security & Privacy for scope and reporting guidance, particularly around prompt-injection-style risks specific to agentic tools.

Key security guarantees:

API keys are never logged, stored in config files, or committed.
Path traversal is blocked by default.
All destructive actions are gated behind confirmation.
Session data is stored locally and never sent to any third-party service.

License

_{Built with ❤️ for developers who want an AI coding partner that actually does the work.}

Name		Name	Last commit message	Last commit date
Latest commit History 15 Commits
.codeagent/skills		.codeagent/skills
.github/workflows		.github/workflows
bin		bin
docs		docs
src		src
test		test
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
eslint.config.js		eslint.config.js
external_plugin_plan.md		external_plugin_plan.md
implementation_plan.md		implementation_plan.md
package-lock.json		package-lock.json
package.json		package.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

🤖 Codeagent

Features

Roadmap

Quick Start

Prerequisites

Install

Setup

Your first session

Usage

Commands

Interactive REPL

One-shot mode

Session management

Undo

Architecture

Data flow for a single turn

Configuration

Key configuration fields

Supported providers

API key

Safety

Tools

Documentation

Extensibility

Contributing

Security

License

About

Releases

Packages

Used by

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

🤖 Codeagent

Features

Roadmap

Quick Start

Prerequisites

Install

Setup

Your first session

Usage

Commands

Interactive REPL

One-shot mode

Session management

Undo

Architecture

Data flow for a single turn

Configuration

Key configuration fields

Supported providers

API key

Safety

Tools

Documentation

Extensibility

Contributing

Security

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages