curl -fsSL https://raw.githubusercontent.com/vicgupta/tinyagent/main/install.sh | shA minimal coding agent in a single static Go binary. It gives an LLM nine tools (read_file, write_file, edit_file, list_files, grep, bash, and start_process, read_process, stop_process for background commands), plus the opt-in update_plan, skill, view_image, apply_patch, delegate, web_fetch, lsp, and MCP resource (list_mcp_resources, read_mcp_resource) tools, and keeps a linear message history until the model submits.
curl -fsSL https://raw.githubusercontent.com/vicgupta/tinyagent/main/install.sh | shThe script downloads the latest release for your OS and CPU, checks it against SHA256SUMS, and installs it to /usr/local/bin if you can write there, otherwise to ~/.local/bin. No sudo needed. Two optional settings:
# Install a specific version
curl -fsSL https://raw.githubusercontent.com/vicgupta/tinyagent/main/install.sh | TINYAGENT_VERSION=v0.1.1 sh
# Install somewhere else
curl -fsSL https://raw.githubusercontent.com/vicgupta/tinyagent/main/install.sh | TINYAGENT_INSTALL_DIR=~/bin shDownload tinyagent-windows-amd64.exe (or -arm64.exe) from the latest release, rename it to tinyagent.exe, and put it in a folder on your PATH. The bash tool needs bash on your PATH, e.g. from Git for Windows.
go install github.com/vicgupta/tinyagent/cmd/tinyagent@latestBinaries for every platform, plus SHA256SUMS, are on the releases page. Verify with shasum -a 256 -c SHA256SUMS --ignore-missing. On macOS, a binary downloaded with a browser is quarantined; clear it once with xattr -d com.apple.quarantine tinyagent.
tinyagent --updateThis replaces the binary in place with the latest release, after checking its checksum. If it's installed in a directory you can't write to, run it with sudo.
Each step is printed to stderr as it happens, and the download shows a # progress bar when stderr is a terminal:
update: current version: v0.10.3 at /usr/local/bin/tinyagent
update: query latest release: https://api.github.com/repos/vicgupta/tinyagent/releases/latest
update: query latest release: found v0.10.4 (current v0.10.3)
update: select asset: tinyagent-linux-amd64 for linux/amd64
update: download checksums: SHA256SUMS
update: download binary: https://github.com/vicgupta/tinyagent/releases/download/v0.10.4/tinyagent-linux-amd64
[####################....................] 50% 4.5 MiB / 9.0 MiB
It ends with the received size, the verified SHA-256, the install step and update: done: updated v0.10.3 -> v0.10.4 at <path>. If a step fails, the error names it: error: update failed at verify checksum: .... See --update for the details.
tinyagent --completion bash, tinyagent --completion zsh and tinyagent --completion fish print a script that completes flag names (--sandbox-<Tab>, --tool-out<Tab>, short aliases such as -t). After --env, --command-env, --reasoning-effort, --openai-api, --sandbox-backend and --completion (as --flag <Tab> or --flag=<Tab>) they also complete that flag's fixed values, so --env <Tab> offers local and container. Other flag values, such as models and profiles, are not completed; those words fall back to filenames.
Bash. Load it for the current session:
source <(tinyagent --completion bash)To keep it, add that line to ~/.bashrc.
Zsh. The script registers itself with Zsh's native completion system (compdef, no bashcompinit), so it must be sourced after compinit. For the current session, or to keep it, put this in ~/.zshrc:
autoload -Uz compinit
compinit
source <(tinyagent --completion zsh)If your framework (Oh My Zsh, Prezto and the like) already runs compinit, add only the last line, after the framework is loaded. Sourcing it before compinit prints an error and changes nothing.
Fish. Load it for the current session:
tinyagent --completion fish | sourceFor automatic loading in new sessions, save the script:
mkdir -p ~/.config/fish/completions
tinyagent --completion fish > ~/.config/fish/completions/tinyagent.fishOther shell names exit 2. In all three shells, words that don't start with - (and flag prefixes that match no flag) keep the shell's normal filename completion, and pressing Tab never runs tinyagent: the flag list is fixed when the script is generated, so re-source it after --update (or open a new shell); for Fish automatic loading, regenerate the saved file after updating. The command needs no task, credentials or config.
git clone https://github.com/vicgupta/tinyagent && cd tinyagent
make build # ./tinyagent
make test
make dist # linux/darwin/windows × amd64/arm64 in dist/export OPENAI_API_KEY=...
tinyagent -t "fix the failing test in pkg/foo" --cwd ~/src/project -o run.json -v
tinyagent -m anthropic/claude-sonnet-4-5 -t "..."
tinyagent -m openrouter/qwen/qwen3-coder -t "..."
tinyagent -m ollama/llama3.1 -t "..."
tinyagent -m codex/gpt-5.6-luna -t "..." # ChatGPT subscription, see docs/providers.md
cat task.md | tinyagent -t - # read a long or multi-line task from stdin
tinyagent --read-only --cwd ~/src/project -t "Review error handling in pkg/api"
cat review-task.md | tinyagent --read-only -t - -o review.jsonRun tinyagent --help (or plain tinyagent at a terminal) for the overview: usage, two examples, the common options (-t/--task, including -t - for stdin; -m/--model with its providers and default; -c, --cwd, --resume, --read-only, -o, --json, --check, --update, -V) and the subcommands, and tinyagent --help --verbose for every flag. Subcommands are shortcuts for common flags: tinyagent sandbox, tinyagent memory list, tinyagent ratchet list, tinyagent planner --first, tinyagent plugins list, tinyagent tinygo status (see CLI reference); each one alone, such as tinyagent sandbox, prints its help.
- Small set of file, search, shell and background-process tools, plus opt-in planning, skills, images, patches, subagents (read-only researchers), workers (read-write builders in their own Git worktree), web fetch, LSP and MCP tools.
- Per-role model routing (
models:in config,--aux-model,--delegate-model,--route, keyword ortask_typeroutes,--no-routing) for compaction, the verify review and delegated children, each role with its own fallback chain and ausage_by_rolecost split in the summary, JSON, trajectory,--log-dband eval reports; off by default. - Many providers: OpenAI, Anthropic, OpenRouter, Ollama, a ChatGPT subscription through Codex, and your own OpenAI-compatible endpoints.
- Streaming text,
--jsonevent output, structured output, SQLite event logs and OpenTelemetry. - Project memory across runs, with approval before entries become active.
- Session handoff for long-running work (
--handoff): each run leaves.tinyagent/handoff.mdwith what it did and what's next, the next fresh run reads it as data, and an optional startup command runs before the first turn; see Session handoff. - Project rules from agent failures (
tinyagent ratchet add): each rule records its incident and an expiry or review condition, is added to the system prompt, and can be enforced as a permission deny rule; see Project rules. - A task planner that can require a plan before any change.
- Run budgets: turn cap, cost limit and token limit (
--token-limit), with an 80% warning to the model; delegates, workers and--attemptsshare the budget, and a run that hits it can be resumed. - Verify before stop (
--verify-on-stop): a run that changed files isn't accepted until a test or build command passes; otherwise it is marked unverified. Optional computational checks (--verify-check, e.g. lint, type check, tests) run in order, cheapest first, before the run may finish; see Computational checks. An optional inferential review (--verify-review) runs last, once every check passes, and reports the model's findings; see Inferential review. - Help everywhere:
tinyagentortinyagent <subcommand>alone at a terminal prints help (the top-level one shows how to pass the task, pick the model and the common options);--help --verboselists every flag by section. tinyagent --update: checksum-verified self-update with step-by-step progress and a#download bar.- Undo for file edits, workspace rewind, resume and follow-up runs.
- Sandboxed commands (Linux: Bubblewrap with Landlock stacked inside, or Landlock alone, via
--sandbox-backend; macOS: Seatbelt) with a network allowlist, permission rules, hooks, untrusted-content lockdown and file-access rules. - WebAssembly plugin modules run through Extism with permission checks, a version store, rollback and prune. Go source modules are built with TinyGo, an external dependency that tinyagent downloads on first use (pinned version, checksum-verified, cached locally,
tinyagent tinygo updateto update); TinyGo is never embedded in tinyagent. - AGENTS.md, Agent Skills, plugins, skill workflows, ACP editor integration and a GitHub Action.
| Topic | Doc |
|---|---|
| Every flag, subcommands and exit status | docs/subcommands.md |
| Config file, profiles, MCP and command tools | docs/config.md |
| Topic | Doc |
|---|---|
| Tasks: passing a task, task types, task-based routing | docs/tasks.md |
| Reviews, worktrees, best-of-N, resume, transcripts, follow-ups, asking for input, token and cost budgets | docs/runs.md |
| Long runs, session handoff, images, tool output files, apply_patch, subagents (read-only researchers), workers (read-write builders), web fetch, LSP | docs/long-runs.md |
Planner (update_plan, --plan-first) |
docs/planner.md |
Verify before stop (--verify-on-stop) |
docs/verify.md |
undo_file and --rewind |
docs/undo.md |
| Project memory | docs/memory.md |
Project rules from agent failures (ratchet) |
docs/ratchet.md |
| AGENTS.md, skills and skill workflows | docs/project-context.md |
| Topic | Doc |
|---|---|
| Models: choosing a model, providers, roles, fallback chains, usage by role | docs/models.md |
| Providers, ChatGPT subscription, reasoning and fallback | docs/providers.md |
--json, streaming, structured output, event log, OpenTelemetry |
docs/json-output.md |
| Topic | Doc |
|---|---|
| Sandboxing, network allowlist, command environment, execution environments | docs/sandbox.md |
| Permissions, hooks, lockdown, secret redaction, file access, extra directories | docs/permissions.md |
| Topic | Doc |
|---|---|
| Plugins, WebAssembly modules, version store and TinyGo | docs/plugins.md |
| WebAssembly code plugins: manifests, deny-by-default permissions, hot swap | docs/wasm-plugins.md |
| Built-in tool notes | docs/tools.md |
| Editor integration (ACP) and GitHub Actions | docs/integrations.md |
| Evaluation framework | docs/eval-framework.md |
| Malformed tool calls, output truncation, troubleshooting | docs/troubleshooting.md |
The experimental Action eval mode runs suites with the verified installer and fails below a pass-rate threshold:
- uses: actions/checkout@v4
with: { fetch-depth: 0 }
- uses: vicgupta/tinyagent@main
with:
version: latest
eval: evals/suite.yaml
eval-out: evals/out
eval-min-pass-rate: '0.8'
cost-limit: '5'
job-summary: 'true'
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
- uses: actions/upload-artifact@v4
if: always()
with: { name: eval-results, path: evals/out }Use full history (fetch-depth: 0) and set a cost limit. Run only trusted suites;
do not expose secrets to untrusted fork PRs. Pin the Action ref and binary
version for reproducible CI once released. See the complete CI example and
outputs, including fork
PR filtering and dry runs.