Smallest Agent
https://github.com/obra/smallest-agent- Category
- AI Agents
- Rank
- No. 1520Tools index
Previous survey · No. 1527 ·
- Pricing
- Open Source
- Type
- AGENT
- Builder
- obra
- GitHub
- 125 stars
- Date
About
A tiny coding agent implemented as a shell script — minimal building blocks for understanding agent design.
What it does
Smallest Agent runs a terminal conversation through Anthropic’s messages API. It preserves prior turns, lets the model request shell commands, returns command output to the conversation, and repeats until the model answers with text.
Why it's ranked here
The project is unusually effective as an executable explanation of an agent loop. A readable source mirrors the compressed implementation, while a live smoke test covers conversation, successful commands, and command failures. Its value is educational clarity, not production readiness.
What's good
The whole control loop remains visible: collect input, call the model, execute requested work, append the result, and continue. Conversation history survives across turns. The readable edition explains each compression choice, and the smoke test checks syntax plus three meaningful paths.
Tradeoffs
The agent gives model-generated commands unrestricted shell access, with no sandbox, confirmation gate, or command policy. Shell execution is synchronous, so long-running commands block the loop. It fixes the model and token limit in code, and its tests require live API access.
How to use it well
Use it to learn agent mechanics, teach tool-calling, or prototype the smallest possible terminal workflow inside an isolated environment. Read the explained source beside the compressed edition. Do not treat it as a secure coding assistant, deployment framework, or substitute for permission controls and sandboxing.
Technical notes+
src/smallest-agent.js is a 493-byte ES module minified from src/smallest-agent.commented.js with Terser. It imports @anthropic-ai/sdk, stores Anthropic-format messages in memory, reads turns from process.stdin, calls the fixed claude-opus-4-6 model with a 4,000-token limit, and exposes an sh tool. Commands run synchronously through child_process.execSync; appending ;: forces a successful shell exit status. package.json maps the mini-agent executable to the minified source. scripts/smoke-test.sh performs a syntax check and live API cases for plain text, uuidgen, and a missing command.
Observed
- Primary language
- JavaScript using ES modules
- Packaging
- npm package named mini-agent with one Anthropic SDK dependency
- Interface
- Command-line executable named mini-agent, using standard input and standard output
- Runtime surface
- Node.js process with direct synchronous shell command execution
- Source structure
- Minified implementation paired with a commented readable equivalent
- Testing
- Bash smoke test against the live Anthropic API
Read from README.md, package.json, src/smallest-agent.js, src/smallest-agent.commented.js, HACKING-TRANSCRIPT.md, scripts/smoke-test.sh.
What it can do
Execute shell commands from natural language instructions
Natural language prompt describing a task → Shell command execution results
Generate code snippets based on user requirements
Description of coding task or problem → Generated code in specified programming language
Interpret and process user prompts for automation
Text-based user instructions → Automated script execution
Demonstrate basic agent architecture patterns
Agent design concepts or requests → Working examples of agent implementation
Provide minimal agent framework for learning
Request for agent building blocks → Simplified agent code structure
Tags
Tech Stack
Comments (0)
No comments yet
Editorially curated, with community endorsements as a secondary signal. Corrections welcome.