README
¶
tinyagent
curl -fsSL https://raw.githubusercontent.com/vicgupta/tinyagent/main/install.sh | sh
A 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.
Install
macOS and Linux
curl -fsSL https://raw.githubusercontent.com/vicgupta/tinyagent/main/install.sh | sh
The 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 sh
Windows
Download 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.
With Go
go install github.com/vicgupta/tinyagent/cmd/tinyagent@latest
Manual download
Binaries 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.
Updating
tinyagent --update
This 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.
Shell completion (Bash, Zsh and Fish)
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 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 | source
For automatic loading in new sessions, save the script:
mkdir -p ~/.config/fish/completions
tinyagent --completion fish > ~/.config/fish/completions/tinyagent.fish
Other 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.
Build from source
git clone https://github.com/vicgupta/tinyagent && cd tinyagent
make build # ./tinyagent
make test
make dist # linux/darwin/windows × amd64/arm64 in dist/
Usage
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.json
Subcommands are shortcuts for common flags: tinyagent sandbox, tinyagent memory list, tinyagent planner --first, tinyagent plugins list, tinyagent tinygo status (see CLI reference).
Features
- Small set of file, search, shell and background-process tools, plus opt-in planning, skills, images, patches, subagents, web fetch, LSP and MCP tools.
- 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.
- A task planner that can require a plan before any change.
- Undo for file edits, workspace rewind, resume and follow-up runs.
- Sandboxed commands 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.
Documentation
| Topic | Doc |
|---|---|
| Every flag, subcommands and exit status | docs/subcommands.md |
| Config file, profiles, MCP and command tools | docs/config.md |
| Providers, ChatGPT subscription, reasoning and fallback | docs/providers.md |
--json, streaming, structured output, event log, OpenTelemetry |
docs/json-output.md |
| Reviews, worktrees, best-of-N, resume, transcripts, follow-ups, asking for input | docs/runs.md |
undo_file and --rewind |
docs/undo.md |
| Project memory | docs/memory.md |
Planner (update_plan, --plan-first) |
docs/planner.md |
| AGENTS.md, skills and skill workflows | docs/project-context.md |
| Plugins, WebAssembly modules, version store and TinyGo | docs/plugins.md |
| Sandboxing, network allowlist, command environment, execution environments | docs/sandbox.md |
| Permissions, hooks, lockdown, secret redaction, file access, extra directories | docs/permissions.md |
| Long runs, images, tool output files, apply_patch, subagents, workers, web fetch, LSP | docs/long-runs.md |
| Editor integration (ACP) and GitHub Actions | docs/integrations.md |
| Built-in tool notes | docs/tools.md |
| Malformed tool calls, output truncation, troubleshooting | docs/troubleshooting.md |
| Evaluation framework | docs/eval-framework.md |
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
tinyagent
command
Command tinyagent is a minimal coding agent: an LLM with file and bash tools.
|
Command tinyagent is a minimal coding agent: an LLM with file and bash tools. |
|
Package embed holds files compiled into the tinyagent binary.
|
Package embed holds files compiled into the tinyagent binary. |
|
internal
|
|
|
acp
Package acp is the agent side of the Agent Client Protocol (https://agentclientprotocol.com), protocol version 1: newline-delimited JSON-RPC 2.0 over stdio.
|
Package acp is the agent side of the Agent Client Protocol (https://agentclientprotocol.com), protocol version 1: newline-delimited JSON-RPC 2.0 over stdio. |
|
agent
Package agent runs the step loop: query the model, execute tool calls, repeat.
|
Package agent runs the step loop: query the model, execute tool calls, repeat. |
|
attempts
Package attempts runs one task up to N times (best-of-N), each attempt as a child tinyagent run in its own Git worktree, grades every finished attempt with user-configured check commands, and picks a verified winner: the lowest-numbered attempt whose run ended Submitted or Completed and whose checks all exited 0.
|
Package attempts runs one task up to N times (best-of-N), each attempt as a child tinyagent run in its own Git worktree, grades every finished attempt with user-configured check commands, and picks a verified winner: the lowest-numbered attempt whose run ended Submitted or Completed and whose checks all exited 0. |
|
config
Package config loads agent settings from an optional YAML file layered over defaults.
|
Package config loads agent settings from an optional YAML file layered over defaults. |
|
eval
Package eval runs a suite of coding tasks against tinyagent and reports how often each model/profile configuration passes the task's own checks.
|
Package eval runs a suite of coding tasks against tinyagent and reports how often each model/profile configuration passes the task's own checks. |
|
eventlog
Package eventlog fans run events out to sinks: the --json JSONL stream and the opt-in SQLite event log.
|
Package eventlog fans run events out to sinks: the --json JSONL stream and the opt-in SQLite event log. |
|
gitwt
Package gitwt holds the Git plumbing for worker subagents: snapshotting a working tree into a commit without touching the index, creating a linked worktree on its own branch, committing a worker's changes, and applying them back to the parent's working tree atomically.
|
Package gitwt holds the Git plumbing for worker subagents: snapshotting a working tree into a commit without touching the index, creating a linked worktree on its own branch, committing a worker's changes, and applying them back to the parent's working tree atomically. |
|
harness
Package harness runs a workflow of minimal markdown skills: a router picks the skills for a task, each skill is one narrow prompt with a success check, and a loop runs them in order, feeding each stage's output to the next and stopping at the first stage that fails its check after retries.
|
Package harness runs a workflow of minimal markdown skills: a router picks the skills for a task, each skill is one narrow prompt with a success check, and a loop runs them in order, feeding each stage's output to the next and stopping at the first stage that fails its check after retries. |
|
hooks
Package hooks runs user-configured commands before and after tool calls, and stop hooks that verify a run before it ends successfully.
|
Package hooks runs user-configured commands before and after tool calls, and stop hooks that verify a run before it ends successfully. |
|
hooks/hookstest
Package hookstest provides a portable hook program for tests: the test binary re-executes itself, so tests need no shell or jq.
|
Package hookstest provides a portable hook program for tests: the test binary re-executes itself, so tests need no shell or jq. |
|
lockdown
Package lockdown holds the run-level taint state of the opt-in untrusted-content lockdown (untrusted_content.enabled / --lockdown, issue #171).
|
Package lockdown holds the run-level taint state of the opt-in untrusted-content lockdown (untrusted_content.enabled / --lockdown, issue #171). |
|
lsp
Package lsp is a small Language Server Protocol client: it starts the configured servers lazily over stdio, keeps the files it has shown them in sync with disk, and collects diagnostics, definitions and references.
|
Package lsp is a small Language Server Protocol client: it starts the configured servers lazily over stdio, keeps the files it has shown them in sync with disk, and collects diagnostics, definitions and references. |
|
lsp/lsptest
Package lsptest is a fake language server for tests: the test binary re-executes itself, so tests need no real language server.
|
Package lsptest is a fake language server for tests: the test binary re-executes itself, so tests need no real language server. |
|
mcptools
Package mcptools connects explicitly configured local MCP servers.
|
Package mcptools connects explicitly configured local MCP servers. |
|
memory
Package memory is tinyagent's cross-run project memory store: short, redacted notes that a run saves about a project and later runs load into their system prompt.
|
Package memory is tinyagent's cross-run project memory store: short, redacted notes that a run saves about a project and later runs load into their system prompt. |
|
model
Package model talks to LLM providers using a single OpenAI-shaped message format.
|
Package model talks to LLM providers using a single OpenAI-shaped message format. |
|
outschema
Package outschema loads a user-supplied JSON Schema for --output-schema and validates a run's structured result against it.
|
Package outschema loads a user-supplied JSON Schema for --output-schema and validates a run's structured result against it. |
|
permissions
Package permissions implements the opt-in tool permission policy: a set of allow/ask/deny rules matched on a tool call's name and one primary argument (a shell command, a path, or a URL host).
|
Package permissions implements the opt-in tool permission policy: a set of allow/ask/deny rules matched on a tool call's name and one primary argument (a shell command, a path, or a URL host). |
|
plugins
Package plugins loads Agent Plugins 1.0.0 packages (https://agent-plugins.org).
|
Package plugins loads Agent Plugins 1.0.0 packages (https://agent-plugins.org). |
|
sandboxnet
Package sandboxnet implements the sandbox network allowlist: entry parsing and matching, and the filtering HTTP proxy that sandboxed commands use.
|
Package sandboxnet implements the sandbox network allowlist: entry parsing and matching, and the filtering HTTP proxy that sandboxed commands use. |
|
skills
Package skills discovers Agent Skills (folders holding a SKILL.md) in the project's and the user's .agents/skills directories, renders the catalog added to the system prompt, and loads a skill's instructions or one of its bundled files for the skill tool.
|
Package skills discovers Agent Skills (folders holding a SKILL.md) in the project's and the user's .agents/skills directories, renders the catalog added to the system prompt, and loads a skill's instructions or one of its bundled files for the skill tool. |
|
snapshot
Package snapshot captures and restores the files under a working directory for opt-in workspace snapshots (--snapshots) and --rewind.
|
Package snapshot captures and restores the files under a working directory for opt-in workspace snapshots (--snapshots) and --rewind. |
|
telemetry
Package telemetry exports runs as OpenTelemetry traces over OTLP/HTTP.
|
Package telemetry exports runs as OpenTelemetry traces over OTLP/HTTP. |
|
tinygo
Package tinygo manages the TinyGo compiler TinyAgent uses to build Go plugin source into WebAssembly.
|
Package tinygo manages the TinyGo compiler TinyAgent uses to build Go plugin source into WebAssembly. |
|
tools
Package tools implements the agent's file and shell tools, sandboxed to a root directory.
|
Package tools implements the agent's file and shell tools, sandboxed to a root directory. |
|
trajectory
Package trajectory records an agent run as JSON.
|
Package trajectory records an agent run as JSON. |
|
transcript
Package transcript renders a saved trajectory as a Markdown transcript for people: the task, each step's assistant text, tool calls and results, the run's plan, compactions, model switches and resume boundaries, and the outcome.
|
Package transcript renders a saved trajectory as a Markdown transcript for people: the task, each step's assistant text, tool calls and results, the run's plan, compactions, model switches and resume boundaries, and the outcome. |
|
update
Package update replaces the running binary with the latest GitHub release.
|
Package update replaces the running binary with the latest GitHub release. |
Click to show internal directories.
Click to hide internal directories.