cli-agent

A zero-dependency terminal and coding agent for Node.js (>= 20). It can inspect projects, edit files, run commands, search the web and resume earlier sessions, with approval before sensitive actions. Inspired by the architecture of EVA.

Features

• Files and code — inspect, search, create and edit workspace files. Proposed writes show a diff before approval and preserve existing line endings.
• Shell access — PowerShell on Windows and bash/sh on Linux or macOS, with bounded output, timeouts and approval before every command by default.
• Project context — reads AGENTS.md, CLAUDE.md or .cli-agent.md so the agent follows project-specific commands and conventions.
• Web and images — fetch pages, search via DuckDuckGo, and attach images from files or the clipboard.
• Providers — Anthropic and OpenAI-compatible services, including OpenAI, Azure, Ollama and OpenRouter, with streaming and optional reasoning modes.
• Resumable sessions — conversations are stored locally and can be resumed, searched or compacted when they grow. Access to previous sessions asks for approval; current-session recall is automatic.
• Visible, reversible work — session-scoped diffs show what changed and can restore files to their state at the start of the session.
• Self-diagnostics and improvement — /self reports live tools, policy, model and session state. /improve reviews recorded friction and requirements; optional causal investigation is bounded and read-only.
• Safety boundaries — workspace reads are automatic; writes, shell commands, outside-workspace reads and private-network requests are gated separately.
• Workspace trust & egress control — unknown repositories start untrusted: project instruction files (AGENTS.md, …) are shown and confirmed before they enter the system prompt, web fetches are approved per domain and search queries individually. Reading a credential-like file (.env, *.pem, credentials*, …) always asks and marks all later web egress approval-required for the session — each approval shows the full URL or query, so local secrets cannot leave silently. /trust switches between trusted, untrusted and offline (web tools disabled).

Setup

Prerequisite: Node.js >= 20 must be installed.

Run the guided setup once:

node src/index.js setup

or, after package installation/linking:

cli-agent setup

The wizard writes the agent's trusted configuration to your user config directory outside any repository (%APPDATA%\cli-agent\config.env on Windows, ~/Library/Application Support/cli-agent/config.env on macOS, ~/.config/cli-agent/config.env on Linux). The generated config.env is based on .env.example, with your answers filled in. Repository .env files are treated as application/repository config and are not loaded as cli-agent configuration.

The wizard can also install a small cli-agent launcher into a user bin directory. If that directory is not already on PATH, it asks before updating your user PATH / shell profile automatically; if you decline, it prints the manual PATH instruction instead.

Then start a session:

npm start
# or: cli-agent

Usage

cli-agent               new session
cli-agent resume [id]   resume latest (or given) session; id prefixes work
cli-agent --list        recent sessions

Inside the chat, /help lists all commands. The most useful ones are:

• /status — model, session, context and token usage.
• /self [section] — runtime and source-based self-diagnostics.
• /improve — review the improvement backlog without changing code.
• /sessions, /resume [id], /new, /delete <id> — manage sessions.
• /compaction [preview|new] — inspect compacted history or continue it in a new session.
• /diff [n|path|last], /undo [n|path|last] — inspect or undo session changes.
• /image <path>, /paste-image, /pi [text] — attach or send images.
• /last [n], /full — re-show tool output; /model [id] — switch models.
• /trust [mode] — show or set workspace trust (trusted|untrusted|offline).

At an approval prompt, y approves, n or Enter declines, f shows full details, and free text declines while giving the agent feedback. For file edits, e opens the proposed content in your editor and d reveals a side-by-side diff when REVEAL_EDITS=1. Use COPILOT_EDITOR, EDITOR or VISUAL to choose the editor; VS Code should be configured as code --wait.

Ctrl+C aborts the current model request or running shell command; press it again to force quit. At the input prompt it exits normally. Unexpected turn errors are reported without discarding the session.

Large terminal pastes are collapsed to a short marker on screen while the full text is still sent to the model.

Configuration (.env)

Variable	Default	Meaning
PROVIDER	anthropic	anthropic | openai | openai_responses | fake
MODEL	—	model id
API_KEY	—	also accepts ANTHROPIC_API_KEY / OPENAI_API_KEY
ENDPOINT	provider default	custom API endpoint
MAX_TOKENS	32000	response cap (Anthropic max_tokens, Responses max_output_tokens - shared by reasoning + answer). Chat Completions only sends max_completion_tokens when set explicitly (local servers with small contexts may reject large caps)
PROMPT_CACHE	1	Anthropic prompt caching
THINKING	off	Anthropic: enables extended thinking (1/adaptive or token budget). OpenAI (Responses API only): none/minimal/low/medium/high/xhigh/max sets reasoning effort (other truthy = medium); every level except none also requests visible summaries; unset = provider default (no reasoning on gpt-5.1+); ignored by Chat Completions
STREAM	1	stream responses
LLM_TIMEOUT	600	total request timeout (s), incl. streaming; reasoning models can think for minutes
LLM_RETRIES	2	retries on transient model errors (never after streaming started)
MAX_STEPS	50	max model rounds per turn before pausing
MAX_TOOL_CALLS	200	max tool actions actually started per turn; excess calls receive cancellation observations
TEMPERATURE	provider default	sampling temperature (opt-in; some models reject a non-default value)
HISTORY_BUDGET	300000	hard estimated serialized UTF-8 provider-payload limit in bytes (includes system, tools, attachments and replay metadata)
HISTORY_KEEP	50	recent-event retention target; content may still be truncated to satisfy the hard budget
STATE_DIR	~/.cli-agent	where sessions, prompt history and generated state are stored
SESSION_FSYNC	0	call fsync after event-log and manifest writes for stronger crash durability (slower; the default relies on normal OS writeback)
AUTO_YES	0	approve everything (no prompts)
TRUST_MODE	per-workspace	override the workspace trust mode for this run (trusted | untrusted | offline) without persisting it. Normally the mode is decided once per workspace (interactive prompt) and stored in the agent's own state dir — never in the repository
ALLOW_SHELL	0	auto-approve shell commands. By default every shell command asks, even apparently read-only ones, because shell text is not a reliable safety boundary. Shell child processes receive a sanitized environment (no inherited provider/API-key variables by default), but shell access is still arbitrary code execution. Note: enabling this effectively bypasses file-write approval too — an auto-approved shell command can write/delete files (rm, Remove-Item, > file). Treat it as full trust.
ALLOW_OUTSIDE_WORKSPACE	0	auto-approve file reads outside the workspace (otherwise gated); does not affect network access and does not unlock protected cli-agent config/state paths
ALLOW_PRIVATE_NETWORK	0	auto-approve web requests to private, loopback or link-local addresses such as localhost or 169.254.x.x (otherwise gated)
COPILOT_EDITOR	notepad on Windows, vi elsewhere	editor for editable file-write approvals (e); EDITOR and VISUAL are also accepted
REVEAL_EDITS	0	at a write approval, d opens the proposed change as a side-by-side diff in your editor (needs AUTO_YES=0)
REVEAL_CMD	code	editor CLI for the reveal; must support --diff a b (e.g. code, cursor)
FRICTION_NOTES	0	offer a bounded causal investigation at the turn boundary (max 4 model steps, 6 read-only calls, 18k tool-output chars; only trace/self-source/self-search). Raw signals are logged regardless; saving the hypothesis still requires confirmation.
PROMPT_SPOTLIGHT	1	mark tool output as untrusted data in the model context (hidden from the terminal); set 0 to disable
DEBUG_SSE	off	path to a file; appends every SSE event type + payload gist (Responses API) — for diagnosing which reasoning/summary events a model emits. Note: reasoning summaries are sparse — short thinking bursts often produce none (model behavior, not a bug)

Session logs and attachments are deliberately transparent plaintext. New session directories/files use restrictive owner-only modes where the platform supports them, and generic model file tools cannot access the state directory, but prompts, tool output and attachments can still contain secrets on disk. Use /delete <id> for sessions you no longer want to retain; there is currently no automatic retention policy or field-level redaction.

Layout

src/
  index.js          entry point / composition root: wires everything below
  core.js           compatibility facade for protocol + loop exports
  protocol.js       canonical provider-neutral events and tool types
  system_prompt.js  agent runtime and workspace prompt policy
  config.js         trusted user configuration
  setup.js          guided setup wizard and launcher install
  approval.js       risk ladder, approval policy and editor-assisted approvals
  diff.js           session-scoped diffs and undo support
  vision.js         image attachments and clipboard image import
  project.js        AGENTS.md / CLAUDE.md project context loader
  self.js           runtime/source self-diagnostics + epistemic labels
  adapters/         provider integrations and streaming/retry handling
  runtime/          agent loop, tool pipeline, argument validation, turn runner
  security/         path/network/egress policies and workspace trust registry
  session/          append-only JSONL stores, active-session switching, compaction
  tools/            shell, file, search, session-recall and web capabilities
  ui/               terminal UI, slash-command registry, onboarding, formatting
  improve/          friction journal, backlog wiring, bounded investigator
test/               node --test suite

Tests

npm test