Skip to content
AAtom
Install

Atom - terminal coding agent

A calm agent for your terminal work.

Reads, edits, and runs code with you. Approval stays visible.

Install AtomGitHub
normal asks firstyolo never asksplan stays read only
atom - agent loop
  1. USERrename the auth helper, keep tests green
  2. PLANtodowrite: 3 steps queued (map, patch, test)
  3. CTXtoken: (12%) 8K
  4. BRANCH2 parallel reads
  5. glob src/**/auth*
  6. grep authHelper
  7. TOOLread src/auth.ts (auto)
  8. ASKedit src/auth.ts - approval: y
  9. RUNbash npm test - 14 passed
  10. DONE2 files changed, suite green

INSTALL IN ONE LINE

npm i -g atom-agent

Default model deepseek-v4-pro. Change anytime with /model.

Start with docs if you read before you run.

How Atom works

Five verified parts orbit one loop. Three more are planned and marked where they will dock. Select any part to inspect it.

Selected

Agent loop

  • Tool results feed back into the next step automatically.
  • Bounded at 30 tool rounds per turn, clamped 5 to 100.
  • Transient failures retry; denials replan instead of retrying.
Read: Tools and caps

One loop, six organs

Each capability below exists in the repository and feeds the same agent loop. Nothing here is a roadmap promise.

Context budget

History allowance derives from the model's verified window minus system, tools, a 4096 token output reserve, and a 5 percent margin. Auto compact fires near 83 percent.

available = window - system - tools - 4096 - 5%
Read: Configuration

13 local tools

Nine read-only executors run free. Write, edit, and bash pause for approval. Outputs truncate with overflow pointers, and long shells run in the background.

read src/auth.ts  # auto
edit src/auth.ts  # asks
Read: Tools

Skills

SKILL.md files load in tiers: names always known, bodies on activation, references on demand. At most one skill auto loads per turn, and deny rules still win.

/skill:name  # frontmatter grants apply
Read: Skills

7 providers, one picker

Zen, OpenAI, Anthropic, DeepSeek, Mistral, Gemini, or any OpenAI-compatible server. Keys resolve env first, then the stored auth file. The live model list wins when reachable.

OPENCODE_ZEN_API_KEY  # wins over stored
Read: Providers

Permissions

Normal asks, yolo never does, plan blocks writes entirely. Scoped allow and deny rules cover single sessions, and deny beats everything including yolo.

/allow bash:npm test*
Read: Permissions

Sessions

Atomic saves survive kills mid-write. Resume restores turns and picks, rewind restores file bytes from silent pre-mutation snapshots. Failed turns never touch the file.

Read: Sessions

Designed to stay fast

No benchmark numbers are published for Atom, so none appear here. What is documented is the architecture that keeps it quick.

Stable prefix caching
System instructions, project overlay, and tool definitions stay byte-identical across POSTs while timestamps and git status split into a trailing block. Cache hits surface only when providers report them, never as zeros.
O(1) context accounting
A running ledger keeps exact message, char, and token counters across pushes and splices, so per-step reads never rescan history. An independent scan verifies the ledger in tests.
Background shell
Long commands return immediately with a task id and run independently while the loop continues. Polling reads temp files, so waiting never blocks reasoning.
Bounded payloads
Reads cap near 64KB and shell streams near 8KB per stream, with overflow pointers instead of silent cuts. Small context stays fast context.
Lean runtime, bounded loop
Tool executors use Node builtins plus fetch only, and every turn ends after at most 30 tool rounds. Termination is structural, not hoped for.

What is not claimed

No latency figures, no token savings percentages, no parallelism beyond background shell tasks. Subagent parallelism does not exist yet and is marked coming soon above.

Read before it writes. Ask before it runs.

That is the whole contract. One key, one command, and an agent that shows its work in your terminal.

Install AtomStart with docsGitHub