enowx
AGENTS.md41 starsChanged 13 days agoMITView on GitHub
Guidance for AI agents and humans working in this repository. Read docs/PLAN.md for the product plan and roadmap. Go 1.27+ is required (MyGo needs it). With an older go, set GOTOOLCHAIN=go1.27.3.
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 31,439 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 repository2 other files it gives its agents.
- docs/agents.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
The file
We split this AGENTS.md into the rules it gives an agent
10 rules. About 1 is common, 4 are distinctive, and 5 are very specific to this project.
≈1
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 9
Test: make test (or go test ./path/to/pkg)
- Very specific: line 110
Keep MyGo out of packages marked No.
- Very specific: line 116
Every change must respect these (see docs/PLAN.md §2):
- Very specific: line 122
No cloud unless set up, no telemetry: Never add network calls to enowX-operated services, except to the cloud whose address the user set …
- Common: line 123
Secrets: Never log secrets. Never send a secret to a remote host without explicit user consent.
- Distinctive: line 128
Reuse before reimplementing: Look for an existing function or package before writing a new one.
- Distinctive: line 132
Concurrency: document which goroutine owns what.
- Distinctive: line 135
No attribution of other projects: Don't write "inspired by", "ported from" or "copied from" in code, comments, docs or commits.
- Very specific: line 139
Test behavior, not implementation details.
- Distinctive: line 142
Don't check in low-value tests (trivial getters, tests that restate the code).
≈ “Common” is an estimate: at least 1 in 5 of the 40,246 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
AGENTS.md
Guidance for AI agents and humans working in this repository. Read docs/PLAN.md for the product plan and roadmap.
Commands
- Build:
make build(outputs tobin/; also builds the Linux daemons the app embeds) - Develop:
make dev(hot reload: rebuilds and relaunches the app on Go changes and replaces its daemon; state lives in~/.enowx-dev, override withDEV_HOME=...) - Test:
make test(orgo test ./path/to/pkg) - Lint:
make lint(go vet+staticcheck) - Installers:
make package(every platform's, intodist/<version>, never published) - Installers on GitHub: the Release workflow, run by hand (the installers as its artifact) or by pushing a tag
v<version>matchingcmd/enowx/mygo.json(also a draft release, published by hand) - Servers' distributions:
scripts/test-distros.sh(docker); the daemon as a systemd service:scripts/test-service.sh - Format:
make fmt(gofmt)
Go 1.27+ is required (MyGo needs it). With an older go, set GOTOOLCHAIN=go1.27.3.
Layout
| Path | What lives there | May import MyGo? |
cmd/enowx | Desktop app entry point (also runs the daemon via enowx daemon) | Yes |
cmd/enowxd | Standalone daemon for servers (serve, bridge) | Via daemon only |
daemon/ | Daemon server: connections, RPC handlers, frame pumps | Via core/session only |
cli/ | The command line (enowx-app ls, spawn, send, wait, …), through the host's daemon (see docs/cli.md) | No |
client/ | Client for the daemon protocol | Only plugins/terminal types for the Conn interface |
proto/ | Wire protocol: frames and message types | No |
core/session | PTY sessions, kept in headless MyGo terminals | plugins/terminal only, never ui |
core/worktree | Git worktree management | No |
core/git | Thin wrappers over the git CLI | No |
core/project | Project folders a daemon knows, in the user's order and groups, stored in ~/.enowx-app/projects.json | No |
core/notes | The user's notes on a host, a Markdown file each in ~/.enowx-app/notes (see docs/notes.md) | No |
core/projectdocs | Project Docs: a project documented as notes under one project note: the first line and Based on lines in the body, catalog and templates, staleness, the approval gate, the guard on agents' writes, the skills (see docs/project-docs.md) | No |
core/features | Which features agents get, per scope (everywhere, host, project, session), resolved for a session; the registry is core/agent.Features (see docs/features.md) | No |
core/notify | How the app notifies of agents: the settings kept in the synced settings, the sounds built in (synthesized), quiet hours | No |
core/usersync | Keeps the user's data (notes, canvases, settings, vault) the same on every host: three-way file sync, merges, conflicts, trash (see docs/user-data-sync.md) | No |
core/noteblocks | A note's structure: its layout blocks (tabs, toggles, columns, callouts, cards), sections, to-dos (see docs/notes.md) | No |
core/iconlib | The SVG icons notes and groups take: Lucide, Tabler and Phosphor kept in the binary (scripts/iconlib.mjs builds them), searched by name and keyword, icon values, the user's SVG cleaned | No |
core/notesio | Notes brought in from other apps (Notion, Obsidian, Evernote, Keep, HTML) and taken out (Markdown, folders, HTML, PDF, a backup) (see docs/notes.md) | No |
core/canvas | The user's canvases on a host (mockups, wireframes, diagrams, boards), their versions, comments, exports and the daemon's drawing of shapes, in ~/.enowx-app/canvas (see docs/canvas.md) | No |
core/designbrief | A design's brief (product, users, tone, first screen, peers, what to remove, what is fixed) as Markdown, for canvases and projects (.enowx/brief.md) | No |
core/designreview | The independent review of a design: the fixed rubric a fresh agent scores screenshots on (1 to 10, the bar 8), what it is told, its verdict read back | No |
core/projectctx | A project's context for agents planning for it (stack, branch, last commit, folders, README) and its files, read-only | No |
core/shells | The shells a host has, for its terminals | No |
core/vault | The user's credential vault: sealed with a key that stays on the device, its platforms, what a session gets of a credential, hosts' imports, the SSH agent and the record of uses (see docs/vault.md) | No |
core/accounts | Agents' configs (synced): other accounts, each a home of its own sharing the agent's settings, and model APIs; team members' accounts per host (see docs/configs.md, docs/accounts.md) | No |
core/agent | Agent presets (Claude Code, Codex, …) and how they take a first prompt | No |
core/platformagent | Claude Platform, enowX's own agent (see docs/claude-platform.md): the loop over Anthropic's Messages API | No |
core/platformagent/record | Its conversation's file format, read by core/transcript and core/tokens | No |
core/platformagent/terminal, tools, permission, mcpclient | Its screen in a session's terminal, its tools, permission rules and MCP client | No |
core/agentapi | How each agent takes a model API: per session by its environment and flags (a config's), or in its own settings, backed up first, for those that can't (see docs/configs.md, docs/agent-api.md) | No |
core/hosts | The device's server list (~/.enowx-app/hosts.json); passwords live in the keychain, never here | No |
core/tailnet | Devices on the user's tailnet, via the tailscale CLI | No |
core/envsync | Copies agents' skills, subagents, commands, memory files, settings and MCP servers between homes (see docs/sync.md) | No |
core/folders | Lists and creates folders, so the app can browse any host's disk when picking a project | No |
core/transcript | Reads the conversations agents record on disk, for the chat view (see docs/chat-view.md) | No |
core/review | A session's changes against its base, and commit, push, pull request (gh), merge and discard (see docs/review.md) | No |
core/checks | Finds and runs a session's checks (tests, linters, build) | No |
core/commands | A project's commands to run (found in its files, saved, run lately), for the Run menu | No |
core/setup | Scans what a host has, keeps what to bring as enowx.toml, and plans the steps that set a server up (see docs/setup.md) | No |
core/transfer | Packs a project and its sessions into an archive, and unpacks it on another host (see docs/transfer.md) | No |
core/projectsync | Compares two hosts' copies of a project with their last sync, plans and runs what goes each way (see docs/transfer.md) | No |
core/projectlinks | A project's ID in its folder, the links between its copies on several hosts, their syncs on their own and its auto push settings (see docs/transfer.md) | No |
core/autopush | Commits a project's work to a branch of its own and pushes that branch alone, the user's branch, index and files untouched, secrets refused | No |
core/decide | The judge: a small model asked instead of guessing (a quiet session's state, approving a command, trimming output, a loop), the judges found on a host (agents' one-shot commands, model APIs, local servers), the policy and order they're tried in, the log (see docs/decide.md) | No |
core/hostkeys | Keys typed in the app for one host's own use (a judge's, RAG's embedder's, a database URL), in a file of that host alone, never synced or sent back to an app | No |
core/rag | RAG: a project's files cut into chunks, embedded (Voyage, OpenAI-compatible, TEI) and kept in SQLite or PostgreSQL with pgvector, searched by meaning and words; the host's settings and consent per project, memories (see docs/rag.md) | No |
core/tokens | Token usage: the agents' records read by an adapter each, model APIs' answers metered, a call a record kept a file a day, prices, budgets, rollups (see docs/tokens.md) | No |
core/diag | The logs of the app and the daemon: events written off the caller's thread, secrets masked, rotation, old logs removed by their exact names, the bundle for a bug report (see docs/diagnostics.md) | No |
core/goa | GOD of Agents: how far each agent holds it to delegating, which of its tool calls are enowX's, which of its workers' calls are the user's (urgent), its task board on disk (see docs/goa.md) | No |
core/hooks | The user's hooks: kept (the host's, synced; a project's .enowx/hooks.json once allowed), which match an event, and running them (see docs/hooks.md) | No |
core/automation | When automations (an agent's prompt on a schedule) run (see docs/automations.md) | No |
core/userservice | Runs the server daemon as a systemd user service, with lingering (see docs/daemon.md) | No |
core/vps | Creates and deletes servers at Hetzner, DigitalOcean, Vultr and InstaBox with the user's token, and InstaBox's certificates to sign in (see docs/vps.md) | No |
core/mcptest | Runs an MCP server where its agent would and lists its tools, for Settings' Test | No |
core/display | Virtual displays for sessions on Linux servers (Xpra), for desktop apps | No |
core/files | Lists and reads a session's folder, with git's marks, for the side panel's Files tool | No |
core/intercept | A host's HTTP interceptor: proxy, TLS with the host's CA, capture, rules, filters, HAR (see docs/traffic.md) | No |
core/android | A host's Android SDK, emulators and devices, their logs, setup, a project's run command, scrcpy (see docs/android.md) | No |
core/discordrpc | Discord Rich Presence over the Discord app's local IPC socket (named pipe on Windows) | No |
core/cacheclean | Clean cache: what a host's enowX folder takes, what can go of it, and removing that, never anything outside the few folders it names (see docs/daemon.md) | No |
core/procstat | Memory and CPU of process trees and of the machine, for the resource usage view | No |
core/selfprofile | What the process it runs in holds and uses, by the system's count and the Go runtime's, for enowx-app profile (see docs/performance.md) | No |
core/memtune | How long-running programs give memory back: the limit on the Go heap, returning what a burst leaves (see docs/performance.md) | No |
cloud/ | The team cloud's server (cloud/server), its database (cloud/store), API types (cloud/api) and the sealing of a team's keys and items (cloud/seal) (see docs/cloud.md) | No |
cloud/library | enowX UI's server, under /v1/library: the community library's API, its web sign-in, moderation (see docs/library.md) | No |
core/designshare | A canvas's design made into what the community library keeps: its bundle and checks, the host's drafts, the code, skills and enowx:// links people take from it; core/designshare/thumb its picture (see docs/library.md) | No |
cmd/enowx-cloud | The cloud server's entry point and its image (Dockerfile) | No |
hostconn/ | Connects to a host's daemon: starts or replaces it locally, installs or upgrades it over SSH | No |
docs/ | The docs, and package docs shipping them in the program for goa doc (all top-level *.md but PLAN.md) | No |
version/ | The release version shared by app, daemon and client | No |
internal/quietcmd | Starts programs in the background without a console window on Windows | No |
internal/watchdog | Leaves a report when a thread stops answering (every goroutine's stack, what was on screen), and a line of what memory holds, in the data folder's watchdog folder | No |
internal/rpccount | A connection counting calls and bytes, for tests saying how often a method is called | No |
internal/testlisten | A test binary standing in for a dev server a session starts, for tests of ports | No |
core/* (others) | Runner, scheduler, store (later) | No |
transport/ | Local socket, SSH, daemon spawning | No |
transport/owntailnet | The app's own device on the user's tailnet (tsnet), apart so the server daemon doesn't carry Tailscale | No |
ui/ | Native UI: the app shell (host rail, session list, workspace with focus and split views, the side panel of tools about the selected session), the rail's pages (Hosts, Sync, Resource usage), the connection flow and host dialogs | Yes |
ui/theme, ui/icon | Palette, fonts, themes; the SVG icons | Yes |
ui/widget | Controls every view shares: buttons, dialogs, menus, chips, Markdown | Yes |
ui/textfmt | How values read in the UI: sizes, plurals, paths | No |
ui/localpicker | Picks files and folders of this device, for adding them to a session's folder | Yes |
ui/chatview, ui/activityview, ui/appwindow, ui/libraryview, ui/communityview, ui/browserview, ui/checkview, ui/diffview, ui/fileview, ui/portview, ui/trafficview, ui/androidview, ui/notesview, ui/canvasview, ui/vaultview, ui/usageview, ui/folderpicker, ui/syncview | Self-contained views; they get what they need from ui through options and callbacks, never import it | Yes |
ui/onboardview | The first run: the app assembling itself, a clock driving the opening, frames, wires and the change of style, the seven steps in a panel; its links in links.go (see docs/onboarding.md); self-contained like the views above | Yes |
ui/platformview | Claude Platform's sheet (API keys, from the vault; its system prompt) and the words its chat says of them; self-contained like the views above | Yes |
ui/projectdocsview | Project Docs on the Notes page: making a project, its summary, a document's strip; self-contained like the views above, drawn through a hook of ui/notesview | Yes |
ui/tokenview | The Tokens tab of Resource usage: every host's token use, budgets, prices, coverage; self-contained like the views above | Yes |
Keep MyGo out of packages marked No. If MyGo ever has to be replaced, only ui/, cmd/enowx and the terminal emulation in core/session should change.
A new feature agents use registers in core/agent.Features (its guide part and MCP tools), so Settings → Features can turn it off. New daemon RPC methods go in the daemon/rpc_*.go file of their domain; TestEveryMethodHasHandler fails when a proto.Method* has no handler. The protocol only grows: go test ./proto fails when a method, event, constant or JSON field it had is gone or changed; record additions with go test ./proto -run API -update (see docs/protocol.md). New UI controls go in ui/widget; a new self-contained view gets its own ui/<name>view package.
Principles
Every change must respect these (see docs/PLAN.md §2):
- Local and remote are the same code path. Everything goes through the daemon. Never add a feature that works only locally or only remotely.
- Agent-agnostic. Any terminal program can be an agent. Agent-specific code lives behind adapters.
- Cross-platform. macOS, Linux and Windows. Guard platform code with build tags (
_unix.go,_windows.go), not runtime string checks scattered around. Start programs withinternal/quietcmd, notos/exec: on Windows a program the app or its daemon starts otherwise flashes a console window (a test fails onexec.Commandin code built for Windows). - Mixed versions. App and daemon update independently. Protocol changes must stay backward compatible or bump
proto.Versionwith a fallback. - No cloud unless set up, no telemetry. Never add network calls to enowX-operated services, except to the cloud whose address the user set (docs/cloud.md): nothing reaches it while unset, and credentials never do.
- Secrets. Never log secrets. Never send a secret to a remote host without explicit user consent.
Code style
- Standard Go:
gofmt, small packages, errors wrapped with context (fmt.Errorf("worktree: add %s: %w", name, err)). - Reuse before reimplementing. Look for an existing function or package before writing a new one.
- No vague names. No
utils,helpers,common,misc. Name files and packages after what they contain. - Comments: explain why, not how. One line when possible. Exported identifiers get doc comments.
- Small files. Split a file when it passes ~400 lines or holds more than one responsibility.
- Concurrency: document which goroutine owns what. Prefer one owner goroutine + channels over shared mutable state; when using a mutex, keep the locked section small and never call out (callbacks, I/O) while holding it.
- UI pages aren't one plain column. Split a page that holds several things with navigation (tabs, a side list) and put making, joining, editing and details of one item in a dialog (
widget.FormSheet,widget.Sheet), rather than stacking every form on the page. - Destructive actions ask first. Signing out, removing or deleting, leaving, stopping what can't be resumed: confirm with what will be lost (
a.confirm,ui.AlertDialog) before doing it. - No attribution of other projects. Don't write "inspired by", "ported from" or "copied from" in code, comments, docs or commits.
Tests
- Test behavior, not implementation details. Prefer end-to-end tests through the daemon protocol (
daemon/server_test.go) over mocks. - Tests that need
libghostty-vtdownload it on first run into the user cache (needs network once). - Sessions in tests run under
SHELL=/bin/sh(eachTestMain), never the user's login shell. By hand, a throwaway daemon stops withENOWX_HOME=<its folder> enowxd stop: withoutENOWX_HOMEit stops the user's real daemon, whatever binary runs it; akillof it or of a session's processes, or a crash, hangs up live terminals, which can leave a stuck/dev/ttysNthat hangs every new shell on the Mac until the process holding it is gone (stat /dev/ttys*finds it). - Don't check in low-value tests (trivial getters, tests that restate the code).
Commits
- Imperative, concise subject (
Add session resize to protocol), body explains why when it isn't obvious. - One logical change per commit.
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.