amika
AGENTS.md301 starsChanged 11 days agoApache-2.0View on GitHub
All Go sources live under go/. The Makefile at the repo root runs go commands with go -C go ..., so make targets continue to work unchanged from the repo root. Build outputs are written to dist/ at the repo root. Use make build to build all binaries (amika, amikad, amikalog, and the experimental akfs and amikalyze), or make build-cli / make build-amikad / make build-amikalog / make build-akfs / make build-amikalyze for one binary. If you run go build…
- Reads credentials
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository11 other files it gives its agents.
- js/AGENTS.mdAGENTS.md
- sandbox-image/AGENTS.mdAGENTS.md
- amika-annotationsSkill
- amika-cliSkill
- create-cli-release-commitSkill
- create-sdk-release-commitSkill
- distill-sessionSkill
- make-stacked-prsSkill
- naive-reader-reviewSkill
- new-specSkill
- release-commit-sandbox-imageSkill
The file
We split this AGENTS.md into the rules it gives an agent
7 rules. About 0 are common, 0 are distinctive, and 7 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 7
All Go sources live under go/.
- Very specific: line 127
All exported symbols must have doc comments (enforced by the exported rule)
- Very specific: line 128
No external dependencies need to be installed for linting.
- Very specific: line 142
Only document commands and behavior that exist in the current code — verify against the go/cmd/ sources.
- Very specific: line 143
No mid-sentence em-dashes in running prose.
- Very specific: line 144
Use the naive-reader-review skill to pressure-test a doc with a cold reader.
- Very specific: line 149
Test targets: make test-unit, make test-integration, make test-contract, make test-expensive
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AGENTS.md
This file provides guidance to AI coding agents when working with code in this repository.
Build and Development Commands
All Go sources live under go/. The Makefile at the repo root runs go
commands with go -C go ..., so make targets continue to work
unchanged from the repo root. Build outputs are written to dist/ at
the repo root.
Use make build to build all binaries (amika, amikad, amikalog, and the experimental akfs and amikalyze), or make build-cli / make build-amikad / make build-amikalog / make build-akfs / make build-amikalyze for one binary. If you run go build directly, do it from the go/ directory and write outputs to the repo-root dist/:
(cd go && go build -o ../dist/amika ./cmd/amika)
(cd go && go build -o ../dist/amikalog ./cmd/amikalog)# Set up git hooks (one-time after clone)
make setup
# Run all CI checks locally (fmt, vet, lint, build, test)
make ci
# Individual targets
make build # builds all stable and experimental binaries
make build-cli # builds dist/amika
make build-amikalog # builds dist/amikalog
make build-akfs # builds dist/akfs (experimental, labs)
make build-amikalyze # builds dist/amikalyze (experimental, labs)
make test # go test ./... (run from go/)
make vet # go vet ./... (run from go/)
make fmt # check formatting
make lint # run revive linter
make zizmor # audit GitHub Actions workflows with zizmor (needs uv)Project Overview
Amika is a Go module that lets people control sandboxed AI agents, focused on use-cases for AI coding agents. The goal is to provide the infra for users to build their own software factories. It includes a CLI tool amika and a Go package go/pkg/amika. The project uses standard Go tooling with a Makefile for common commands.
The repo also ships amikalog, a separate, separately-installed CLI that captures Claude Code and Codex hook activity (with the git state of each hook's working directory) as raw append-only events under the amika state directory. Run amikalog start once to install the hooks. It is versioned and released independently of amika (tags amikalog@v*).
This repository is an OSS monorepo. Go sources live under go/. Other
language SDKs live under sdk/ (e.g. sdk/typescript/). TypeScript packages
that are consumed as source rather than published live under js/: among them
js/sandbox (@amika/sandbox), the sandbox provider abstraction, and
js/service-auth (@amika/service-auth), who may reach a rig's service. See
js/AGENTS.md for the conventions every js/ package
follows.
There are two independent pnpm workspaces here, on purpose. The repo root
governs js/* and eslint-rules (root pnpm-workspace.yaml and
pnpm-lock.yaml); sdk/typescript governs itself, with its own workspace file,
lockfile, and packageManager pin, because it is a published npm package with
its own release pipeline. Run pnpm install at the root for the former and
from sdk/typescript/ for the latter.
js/sandbox, and js/service-auth which it depends on, are consumed by
amika-mono as a git submodule pinned to an exact commit, so this repo is the
single source of truth for those packages: changes
land here and reach amika-mono through a pointer bump. That also means this
repo's CI and pre-commit hook own the package's source quality — amika-mono
sees only a gitlink for the submodule and so cannot lint or format it.
Comments and docstrings here sometimes point at amika-mono, Amika's private
control-plane monorepo, for protocol details owned by that side (e.g. "the
ssh-relay repo's specs/019-sandbox-ssh-stream-relay.d/...",
devdocs/sandbox-secret-scrubbing.md). This repo's own specs/ directory is
numbered separately and covers only OSS-specific specs. Look for amika-mono
checked out as a sibling worktree rather than searching for those paths in this repo.
Runtime Dependencies
- The
amikaCLI itself is remote-only: everyrig/sandboxcommand talks to the Amika API. The former--localmode, thevolumeandmaterializecommands that served it, and the Docker-backedpkg/amika.Servicebehind them have been removed.
Code Structure
CLI Commands (go/cmd/amika/)
Conventions for commands (help text, replacing flags, --output/-o JSON, rig arguments) live in go/cmd/amika/AGENTS.md.
main.go— Entry point, root Cobra commandsandbox.go—sandbox create|list|connect|deletecommandshost.go—host list|get|deletecommands over the org's own hosts (BYOC); hosts are registered byamika-hostd, not hereauth.go—auth login|logout|statuscommandsauth_api_key.go—auth api-key create, which mints an API key and writes its value only to the--outfile (never the CLI's own output, errors, or-o json)skill.go—skill install --global|--local [--agents ...], which writes theamika-cliagent skill embedded in the binary into each agent's skill directory (logic ininternal/agentskill)
amikalog CLI (go/cmd/amikalog/)
main.go— Entry point, root Cobra commandstart.go—start/stopcommands that install/remove the agent hookshook.go—hook --source claude|codex, the hook entrypoint that records one eventpush.go—beta:push, uploads not-yet-pushed events to the org storage bucket (auth viaAMIKA_API_KEYonly; requests a signed upload URL per file fromPOST /api/v0beta1/storage/uploads/batch, then PUTs the bytes)fetch.go—beta:fetch <destination>, downloads the entire org storage bucket into a local directory, recreating the bucket key tree on disk (auth viaAMIKA_API_KEYonly; lists the bucket viaGET /api/v0beta1/storage/downloads, paging throughnext_cursor, then GETs each object's signed download URL)
Internal Packages (go/internal/)
sandbox/— Rig preset and GitHub auth mode validation, random rig names, and the embedded sandbox image bundleauth/— Multi-source credential discovery (Claude, Codex, OpenCode, Amp) with priority-based deduplicationconfig/— XDG path resolution, state file location helpersbasedir/— XDG base directory resolutionoutput/— CLI output formatting for the--output/-oflag (text,json,json-pretty)services/— Shared sandbox-service logic used by CLI and API, e.g.ValidatePort(rejects out-of-range and reserved container ports)rigref/— Parses rig references (a name or id,name=/id=to pin the field,_selffor the current rig); rules for commands that take a rig are ingo/cmd/amika/AGENTS.mdagentskill/— Agent names, per-agent skill directories, and the copy behindamika skill installeventlog/— amikalog's hook installer, event capture, and push (details in the package doc)
Public Package (go/pkg/amika/)
types.go— Rig types the CLI renders (Sandbox,PortBinding,SandboxCreator)
Labs / Experimental Code (go/labs/)
- Experimental, unstable code with no compatibility guarantees; stable code (
go/cmd/*,go/pkg/amika,go/internal/*) must not import from it. Holds theakfsCLI and library plus theamikalyzefrozen-path CLI and library. - See
go/labs/AGENTS.mdbefore working there.
Other
dist/— Build output directory at the repo root (gitignored)bin/amika— Wrapper script that auto-builds and runsdist/amikabin/amikalog— Wrapper script that auto-builds and runsdist/amikalogbin/amikalyze— Wrapper script that auto-builds and runsdist/amikalyzesandbox-image/— Shared manifest, build steps, assets, verification suite, and generated Dockerfiles. It also holds generated copies of theamika-cliskill: edit only.agents/skills/amika-cli/, then runpython3 sandbox-image/generate.py(CI fails on a stale copy). The copy in the Go-embed mirror is also whatamika skill installwrites, viasandbox.AgentSkillFSsdk/typescript/— TypeScript SDK
Development Notes
- Requires Go 1.26.10 or later, excluding 1.27.0–1.27.2 (
makerejects them) - Linting uses revive — config in
go/revive.toml - All exported symbols must have doc comments (enforced by the
exportedrule) - No external dependencies need to be installed for linting;
make lintusesgo run - GitHub Actions workflows are audited by zizmor (
make zizmorlocally,.github/workflows/zizmor.ymlin CI). Pin everyuses:to a full commit SHA with a trailing# vX.Y.Zcomment (Dependabot bumps both), declare least-privilegepermissions:, and check out withpersist-credentials: falseunless a later step pushes. Suppress a finding that does not apply with# zizmor: ignore[<audit>]plus a comment saying why - The Amika API (amika-mono's control plane) and its clients here (the CLI, the TypeScript SDK) ship together, API first. Don't add extra requests, client-side checks, or fallbacks for older servers unless asked.
- Ports 60899–60999 are reserved inside sandbox containers for Amika services. See
docs/sandbox-configuration.mdfor the allocation table. Any command or API that accepts a user-specified container port must reject this range by callingservices.ValidatePort(go/internal/services); keep client-side and server-side validation in sync.
Commits and Pull Requests
Format PR titles and descriptions as git commit messages: merging a PR, squashed or not, makes the PR message the commit message on main.
Documentation Style
For user-facing docs (docs/, README):
- Lead with the value prop: what the problem is and why it matters, then the solution, then how to use it. Reference tables (commands, env vars, schemas) come after the narrative, not instead of it.
- Only document commands and behavior that exist in the current code — verify against the
go/cmd/sources. Don't import claims from marketing material describing future features. - No mid-sentence em-dashes in running prose; the
**Term** — descriptionseparator in bullet lists is fine. - Use the
naive-reader-reviewskill to pressure-test a doc with a cold reader.
Testing Notes
- Docker must be running for integration tests and CLI end-to-end testing
- Test targets:
make test-unit,make test-integration,make test-contract,make test-expensive - The Docker-gated suites (
AMIKA_RUN_DOCKER_INTEGRATION,AMIKA_RUN_EXPENSIVE_TESTS) currently have no tests opting into them; they were removed with the CLI's--localmode. Seedocs/development/testing.md - See
docs/development/testing.mdfor the full smoke test plan - On macOS run
go test ./...withTMPDIR=/tmp: the default temp dir is too long for the unix sockets theinternal/sshtests create - Cobra does not reset
rootCmdflag state betweenExecutecalls, so CLI tests that set flags must reset them afterward (seeresetChangedFlagsincmd/amika)
Environment Variables
| Variable | Purpose |
AMIKA_STATE_DIRECTORY | Override default state directory (~/.local/state/amika) |
AMIKA_API_URL | Override remote API base URL (default: https://app.amika.dev) |
AMIKA_BINARY_PATH | Absolute path to the amika executable recorded in generated config (the SSH ProxyCommand). Defaults to the running binary; set it inside a wrapper script so the wrapper names itself and the environment it exports survives |
AMIKA_WORKOS_CLIENT_ID | Override default WorkOS client ID for amika auth login |
AMIKA_RUN_EXPENSIVE_TESTS | Gate for expensive Docker integration tests. No test opts into it today; see docs/development/testing.md |
Cursor Cloud specific instructions
See AGENTS.cursor.md.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

