agnt
AGENTS.md22 starsChanged 11 months agoApache-2.0View on GitHub
Gives AI coding agents browser superpowers: a daemon-backed reverse proxy, process manager, and PTY wrapper that bridge the agent and a real browser for debugging, wireframing, and visual feedback. Run tests through tman (or the repo shims) per the global standards. Design decisions that everything else follows:
- Installs packages
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 33,315 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 repository7 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- daemon-debugSkill
- daemon-health-checkSkill
- flake-triageSkill
- messaging-queueSkill
- searchSkill
- security-boundary-reviewSkill
The file
We split this AGENTS.md into the rules it gives an agent
3 rules. About 0 are common, 1 is distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 11
Run tests through tman (or the repo shims) per the global standards.
- Distinctive: line 51
Daemon state is a cache; the OS is the truth: Verify processes, ports, and proxies against the OS before reporting them.
- Very specific: line 61
Every listener ships loopback-only (127.0.0.1, never 0.0.0.0).
≈ “Common” is an estimate: at least 1 in 5 of the 42,283 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
agnt
Gives AI coding agents browser superpowers: a daemon-backed reverse proxy, process manager, and PTY wrapper that bridge the agent and a real browser for debugging, wireframing, and visual feedback.
- Repository: https://github.com/standardbeagle/agnt — version is managed by
scripts/release.sh(never hand-edit version numbers). - One real binary,
agnt(cmd/agnt).agnt-daemonis a copy used for daemon auto-start because sandboxes forbid self-exec;devtool-mcpis a legacy alias. - The Claude Code plugin lives in a separate marketplace repo; this repo ships the binary and MCP server only.
Build and test
Run tests through tman (or the repo shims) per the global standards.
make build # agnt binary
make all # build + the agnt-daemon copy
make vendor-check # vendor/ must equal what go.mod resolves to (no make: `tman vendor-check`)
make install-local # ~/.local/bin
make test # default suite (host-safe; excludes procisolation/sshe2e/chromee2e tags)
make test-pkg PKG=./internal/incident RUN=TestBus # focused, serial; PKG/RUN both optional
make bench PKG=./internal/incident BENCH=Bus_EndToEnd COUNT=5 # -run '^$', -benchmem; no ordinary tests
make test-isolated # procisolation tests inside a PID namespace (Linux)
make test-ssh # SSH harness + containerized sshd smoke (loud skip without Docker/Podman)
make test-chrome-e2e # real-Chrome tests — unloaded machine only, never alongside other runs
make test-js # vitest + jsdom tier for injected scripts (loud skip without npm); JSFILTER=name narrows, npm ci runs only when the lockfile changed
make cross-compile-check # windows/amd64 + darwin/arm64 build (no make: `tman cross-compile-check`)
make install-hooks # once per clone: core.hooksPath=.githooks- Full-suite gate is
go test -p 1 ./...(serial packages). Parallel./...fails on cross-package port contention, not product bugs. CI runs it withgo vet ./...andmake vendor-checkon every push and pull request (.github/workflows/test-linux.yml). - The pre-commit hook (
.githooks/pre-commit) runs gofmt,go vet, andgo test -race -p 1on staged packages and blocks on failure.--no-verifyis allowed in exactly two cases — see.claude/rules/testing-parallel-package-flakes.md§ Sanctioned--no-verifycases. - Tests that start real OS processes must not use
t.Parallel(). - Daemon tests use
NewForTest, neverStart().
Architecture
| Layer | Where |
| MCP tools (daemon-aware, IPC only) | internal/tools/ |
| Daemon: persistent state, socket IPC hub | internal/daemon/ |
| Text IPC protocol | internal/protocol/ |
| Business logic: project detection, reverse proxy | internal/project/, internal/proxy/ |
| Process management (our module, vendored) | github.com/standardbeagle/go-cli-server/process — there is no internal/process |
| Incident pipeline (the only agent alert path) | internal/incident/ |
| PTY overlay UI | internal/overlay/, cmd/agnt/overlay*.go |
Design decisions that everything else follows:
- Binary copies, not self-exec — sandboxes block a binary forking itself.
agnt runinjects browser events into the agent — MCP cannot push, so a PTY wrapper writes synthetic stdin: Browser → Proxy → overlay (per-session Unix-domain socket) → PTY stdin → agent.- Agent context injection — Claude Code via
--append-system-prompt; other agents via their context file (docs/agent-adapters.md). - Daemon state is a cache; the OS is the truth. Verify processes, ports, and proxies against the OS before reporting them.
- Lock-free by default —
sync.Mapregistries, atomic state,CompareAndSwapState()transitions. - No silent failures — anything declared in
.agnt.kdleither happens or surfaces a visible event to the agent and session log;debug.Logalone is not enough. - Session scoping is the default; global is the audited exception (
scope.Scope,resolveProjectScope). internal/overlaymust not be imported byinternal/daemon(import cycle) — pass data over IPC, interfaces, or strings.
Detail loads automatically from .claude/rules/ when you open files in the matching packages.
Exposure posture (operator decision, 2026-07-31)
Every listener ships loopback-only (127.0.0.1, never 0.0.0.0). Only the operator widens exposure; an agent never does.
| Listener | Default | Widened only by |
Dev proxy (internal/proxy/server.go) | loopback | tunnel, or bind / cloudflare-tunnel in .agnt.kdl |
Public walkthrough plane (internal/daemon/publish_public.go) | off | AGNT_PUBLIC_ADDR |
agnt publish serve (cmd/agnt/publish_serve.go) | loopback | --tunnel |
Overlay (cmd/agnt/overlay.go, ai_overlay.go) | per-session Unix-domain socket, no TCP port | nothing |
| Daemon control socket / named pipe | uid-scoped | nothing |
Operator-granted exception (2026-10-22): the proxy tool (start with bind_address / allow_external / public_url) and the tunnel tool are available to the agent by design, so an agent can widen the dev proxy beyond loopback or start a public tunnel without a .agnt.kdl edit. allow_external is a typed confirmation, not an operator gate. Everything else in the table stays operator-only.
Grades: tunnel cloudflare/ngrok are public and unauthenticated; a cloudflare-tunnel block is public behind Cloudflare Access; tunnel tailscale and bind "tailscale" are tailnet-private. A non-loopback, non-tailnet bind requires allow-external; the tailnet exemption is checked on the resolved address (platform.IsTailnetAddress), never the token.
Reaching a listener is not the same as driving the agent. The dev proxy's control WebSocket classifies each connection once, at upgrade (controlCallerTrusted, internal/proxy/ws_handler.go): agent-input, secret, session/store and voice frames are accepted only from a Cloudflare Access-verified caller, an identified tailnet peer, or the local browser (loopback peer, loopback Host and Origin on the proxy's port, no reverse-proxy headers). An unauthenticated tunnel visitor is refused them. The local-browser rule is applied only while no public URL is bound to the proxy, or the bound one was set by a tunnel agnt itself started of a kind captured live (a Cloudflare quick tunnel, tailscale serve, or ngrok on its own domains), or is the proxy's own named tunnel; the tunnel's kind decides, never the URL's hostname. With ngrok on a custom domain, or a public-url bound any other way, the local browser is refused too.
Page telemetry from an untrusted connection is recorded marked untrusted (proxy.LogEntry.Untrusted): it is never pushed over the channel, an untrusted browser error is a separately fingerprinted browser_js_untrusted incident whose text is labelled, an error response to an untrusted HTTP caller (httpCallerTrusted) is no incident for a 4xx and a labelled http_5xx_untrusted warning for a 5xx, and proxy exec is sent to and answered by trusted connections only. Residual: on pull surfaces the marker is a label, not a barrier — an agent that reads proxylog or currentpage on a publicly tunnelled proxy is reading visitor-authored text.
The first three listeners are hardened to public standard in every posture: read-header and idle timeouts, MaxHeaderBytes, a concurrent-connection cap, and a request-rate cap. The two publish listeners also bound the whole request read and response write. The dev proxy streams, so it has no whole-request deadline; instead a captured request body gets a 30s read deadline and a streamed one a 30s idle deadline per read (request_body_idle.go). Its residual: a client that stops reading a streamed response holds that connection until it disconnects. Unbounded is a defect. Every share route is rate-capped. Known residuals: upstream fetches are not cached (the outbound bounds are a per-origin rate cap and a plane-wide concurrency ceiling), and per-client limits are keyed on the socket peer except behind a tunnel agnt publish serve --tunnel started itself (client address from the tunnel's forwarding header; captured live for Cloudflare, tailscale and ngrok), so behind an operator's own reverse proxy, and on the daemon's AGNT_PUBLIC_ADDR listener, every viewer shares that hop's address.
Conventions
- KDL for app config (
.agnt.kdl); JSON for content data, API contracts, and LLM-facing formats. - MCP tool errors are
CallToolResult{IsError: true}, never Go errors. github.com/standardbeagle/go-sdkis a fork of the MCP go-sdk addingServerSession.Notify; used without areplacesogo installworks. Swap back when upstream PR #898 merges.go-cli-serverandvt10xare our own modules.vendor/is a plain copy of the module versions ingo.mod; never edit a file under it. A fix togo-cli-server(or any dependency) goes upstream and arrives as a version bump, because a patch that lives only invendor/is dropped by the nextgo mod vendorand never reachesgo installbuilds.make vendor-checkenforces this in CI and in the release build.
Where things are documented
| Topic | Location |
Per-tool params, __devtool API, agnt monitor | docs/mcp-tools.md |
.agnt.kdl reference | docs/configuration.md |
| Remote SSH | docs/remote-ssh.md |
| Overlay internals | docs/overlay-internals.md |
| Hooks, channel mode | docs/hook-dispatcher.md, docs/hook-rules.md, docs/channel-mode.md |
| Public walkthroughs | docs/public-walkthroughs.md |
| Flake registry | docs/testing-flake-registry.md |
| Doc index | docs/README.md |
| Codebase map | search skill |
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.

