shivasaini04shivasaini04/nanocrew/AGENTS.md

nanocrew

AGENTS.md4 starsChanged 27 days agoMITView on GitHub

NanoCrew is a self-hosted multi-agent platform. A Node/TypeScript orchestrator (SQLite) runs agents as Docker containers; each container runs the Python nanoagent runtime. A React dashboard talks to the orchestrator, and a LiteLLM gateway sits in front of the model providers. See docs/architecture.md. CI (.github/workflows/) runs format check, typecheck, tests and the dashboard build on Linux, and a Docker quickstart that builds the agent image and runs docker compose up. Run the same before you push. - TypeScript is ESM with…

Reads credentials
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 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 repository9 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- add-parallelSkill
- customizeSkill
- debugSkill
- get-qodo-rulesSkill
- qodo-pr-resolverSkill
- setupSkill
- updateSkill
- x-integrationSkill

The file

We split this AGENTS.md into the rules it gives an agent

2 rules. About 0 are common, 0 are distinctive, and 2 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.
2
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific
could be automatic: a setting could enforce it

Very specific:
Put a test next to the code (foo.ts and foo.test.ts).
line 43
Very specific:
Never commit .env, anything under data/ or store/, databases, tokens or real customer data.
line 48

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

Working on NanoCrew (for contributors and coding agents)

NanoCrew is a self-hosted multi-agent platform. A Node/TypeScript orchestrator (SQLite) runs agents as Docker containers; each container runs the Python nanoagent runtime. A React dashboard talks to the orchestrator, and a LiteLLM gateway sits in front of the model providers. See docs/architecture.md.

Layout

Path	What it is
`src/`	Orchestrator. `index.ts` is the entry; `agents/` (agent lifecycle, scheduling, memory, handoffs), `api/` (REST + sockets), `swarm/`, `channels/` (dashboard, WhatsApp), `owner-notify/`, `db.ts` (SQLite schema and queries)
`dashboard/`	React + Vite SPA, its own `package.json`. Built into the orchestrator image; `dashboard/dist` is never committed
`container/Dockerfile`	The agent sandbox image (built by `container/build.sh`)
`container/nanoagent/`	The Python agent runtime: `agent/` (loop, tools, memory, browser "effector"), `providers/`, `channels/`, `skills/` (built-in skills), `tests/`
`container/agent-runner/`	Container-side runner for group-chat agents; `src/container-runner.ts` talks to it
`skills-engine/`	Applies and updates skills that change the orchestrator source
`.claude/skills/`	Claude Code skills for maintainers (`setup`, `debug`, `update`, `customize`) and a few other skills (`x-integration`, `add-parallel`, `get-qodo-rules`, `qodo-pr-resolver`) that `skills-engine` can apply. The old Discord/Slack/Telegram/Gmail/voice/Apple-container templates were removed on 19 Oct 2026 because they no longer matched `src/`. Separate from the agents' own skills in `container/nanoagent/nanoagent/skills/`
`setup/`	The `npm run setup` helper
`companion/`, `extension/`	Local browser companion and Chrome extension
`docs/`	User docs. `groups/*/CLAUDE.md` are the agents' own instructions, not contributor notes

Commands

npm install && npm run build      # orchestrator, output in dist/
npm run dev                       # orchestrator with reload
npm run typecheck                 # tsc --noEmit
npm test                          # vitest (orchestrator, dashboard lib tests, companion, skills-engine)
npm run format                    # prettier, src/ only
cd dashboard && npm install && npm run dev      # dashboard on :5173
cd dashboard && npx tsc -b && npm run build     # dashboard types and build
cd container/nanoagent && pip install -e ".[dev]" && pytest    # agent runtime
bash container/build.sh && docker compose up --build            # full stack, see README

CI (.github/workflows/) runs format check, typecheck, tests and the dashboard build on Linux, and a Docker quickstart that builds the agent image and runs docker compose up. Run the same before you push.

Conventions

TypeScript is ESM with .js extensions on relative imports. Prettier formats src/**/*.ts; a husky pre-commit hook runs npm run format:fix.
Put a test next to the code (foo.ts and foo.test.ts). A bug fix comes with a test that fails without it.
Database changes are additive: new tables use CREATE TABLE IF NOT EXISTS, new columns an ALTER TABLE in a try/catch (see db.ts). Do not rewrite existing rows' meaning.
Config comes from .env (see .env.example). Read optional numbers carefully: an empty VAR= arrives as "", and Number("") is 0. Keep numeric overrides commented out in .env.example.
Never commit .env, anything under data/ or store/, databases, tokens or real customer data. Use fictional names in tests and fixtures.
Adding third-party code: MIT-compatible only, keep the notice, list it in THIRD_PARTY.md.

Gotchas

Agents run in containers and see host paths through HOST_PROJECT_ROOT; a wrong value shows up as cycles failing to find files.
dist/ is mounted into the orchestrator container: after changing src/, run npm run build and restart.
Warm NanoCrew-daemon-* containers survive image rebuilds; remove them to pick up container changes.
Windows: clone to a short path (the better-sqlite3 build fails on long ones). Some skills-engine and setup tests assume Linux/macOS paths and fail on Windows; they pass in CI.
The companion tests that drive a real Chrome are skipped on CI unless RUN_BROWSER_TESTS=1.

Before you open a PR

See CONTRIBUTING.md. Keep PRs small, explain the why, and say how you tested it.

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.

Check your setup, free