agentleFS
standardbeaglestandardbeagle/agnt/AGENTS.md

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.

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
  1. Very specific:

    Run tests through tman (or the repo shims) per the global standards.

    line 11
  2. Distinctive:

    Daemon state is a cache; the OS is the truth: Verify processes, ports, and proxies against the OS before reporting them.

    line 51
  3. Very specific:

    Every listener ships loopback-only (127.0.0.1, never 0.0.0.0).

    line 61

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

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-daemon is a copy used for daemon auto-start because sandboxes forbid self-exec; devtool-mcp is 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 with go vet ./... and make vendor-check on every push and pull request (.github/workflows/test-linux.yml).
  • The pre-commit hook (.githooks/pre-commit) runs gofmt, go vet, and go test -race -p 1 on staged packages and blocks on failure. --no-verify is allowed in exactly two cases — see .claude/rules/testing-parallel-package-flakes.md § Sanctioned --no-verify cases.
  • Tests that start real OS processes must not use t.Parallel().
  • Daemon tests use NewForTest, never Start().

Architecture

LayerWhere
MCP tools (daemon-aware, IPC only)internal/tools/
Daemon: persistent state, socket IPC hubinternal/daemon/
Text IPC protocolinternal/protocol/
Business logic: project detection, reverse proxyinternal/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 UIinternal/overlay/, cmd/agnt/overlay*.go

Design decisions that everything else follows:

  1. Binary copies, not self-exec — sandboxes block a binary forking itself.
  2. agnt run injects 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.
  3. Agent context injection — Claude Code via --append-system-prompt; other agents via their context file (docs/agent-adapters.md).
  4. Daemon state is a cache; the OS is the truth. Verify processes, ports, and proxies against the OS before reporting them.
  5. Lock-free by default — sync.Map registries, atomic state, CompareAndSwapState() transitions.
  6. No silent failures — anything declared in .agnt.kdl either happens or surfaces a visible event to the agent and session log; debug.Log alone is not enough.
  7. Session scoping is the default; global is the audited exception (scope.Scope, resolveProjectScope).
  8. internal/overlay must not be imported by internal/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.

ListenerDefaultWidened only by
Dev proxy (internal/proxy/server.go)loopbacktunnel, or bind / cloudflare-tunnel in .agnt.kdl
Public walkthrough plane (internal/daemon/publish_public.go)offAGNT_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 portnothing
Daemon control socket / named pipeuid-scopednothing

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-sdk is a fork of the MCP go-sdk adding ServerSession.Notify; used without a replace so go install works. Swap back when upstream PR #898 merges.
  • go-cli-server and vt10x are our own modules. vendor/ is a plain copy of the module versions in go.mod; never edit a file under it. A fix to go-cli-server (or any dependency) goes upstream and arrives as a version bump, because a patch that lives only in vendor/ is dropped by the next go mod vendor and never reaches go install builds. make vendor-check enforces this in CI and in the release build.

Where things are documented

TopicLocation
Per-tool params, __devtool API, agnt monitordocs/mcp-tools.md
.agnt.kdl referencedocs/configuration.md
Remote SSHdocs/remote-ssh.md
Overlay internalsdocs/overlay-internals.md
Hooks, channel modedocs/hook-dispatcher.md, docs/hook-rules.md, docs/channel-mode.md
Public walkthroughsdocs/public-walkthroughs.md
Flake registrydocs/testing-flake-registry.md
Doc indexdocs/README.md
Codebase mapsearch skill

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.