timmo001timmo001/notes/AGENTS.md

notes

AGENTS.md2 starsChanged 20 days agoApache-2.0View on GitHub

This repo contains the standalone notes CLI and MCP server. Run these after source changes: CI validates .agents/skills/ with the shared lint-agent-skills workflow.

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

9 rules. About 0 are common, 2 are distinctive, and 7 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
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
could be automatic: a setting could enforce it

Very specific:
Keep code at the repo root under src/.
line 15
Very specific:
Keep CLI definitions and metadata in the Effect Command tree in src/index.ts.
line 16
Distinctive:
Do not hand-edit generated docs pages.
line 18
Very specific:
Keep portable Notes skills under .agents/skills/, with separate notes-cli and notes-mcp workflows.
line 19
Very specific:
Update order: notes source -> skills import -> skills main -> dot update.
line 32
Very specific:
After an authorised source commit and push, run ./dist/skill-maintenance import notes-cli --apply in the skills checkout.
line 33
Very specific:
Start the capture PWA dev server with mise run serve:capture and the docs dev server with mise run serve:docs.
line 38
Very specific:
Use the :status, :logs, :restart and :stop variants of each, such as mise run serve:docs:logs, to manage them.
line 39
Distinctive:
Run these after source changes:
line 45

≈ “Common” is an estimate: at least 1 in 5 of the 36,368 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

notes agents

This repo contains the standalone notes CLI and MCP server.

Stack

Runtime and package manager: Bun.
Language: TypeScript.
Effects and services: Effect v4.
Docs: Astro + Starlight under docs/.
Task runner: mise.

Rules

Keep code at the repo root under src/.
Keep CLI definitions and metadata in the Effect Command tree in src/index.ts; help, completions, and generated docs consume it.
Regenerate generated docs with mise run docs:gen after changing CLI or MCP metadata.
Do not hand-edit generated docs pages.
Keep portable Notes skills under .agents/skills/, with separate notes-cli and notes-mcp workflows. Keep OpenCode plugins, commands, guards, and integration-specific skills in dotfiles.
Repository notes live under projects/{owner}/{repo}. When no repository can be resolved, use the local scope under projects/local/{project}; automated captures use projects/local/captures.

Omarchy Plugin

omarchy-plugin/ is the source of truth for the Notes Omarchy plugin. Edit it here, not in the published timmo001/omarchy-notes checkout, a dotfiles submodule, or the live plugin directory.
Pushing plugin changes to Notes main runs .github/workflows/publish-omarchy-plugin.yml, which validates and publishes omarchy-plugin/ to timmo001/omarchy-notes. Do not push to the published repository directly.
Validate plugin changes with omarchy plugin validate . and the QML lint command in omarchy-plugin/README.md, run from omarchy-plugin/.

Skill Ownership And Updates

This repository owns .agents/skills/notes-cli/SKILL.md and .agents/skills/notes-mcp/SKILL.md.
timmo001/skills imports only notes-cli as an unchanged snapshot. Edit the source here, not the imported or installed copy. notes-mcp remains available from this repository for explicit MCP use.
Update order: notes source -> skills import -> skills main -> dot update.
After an authorised source commit and push, run ./dist/skill-maintenance import notes-cli --apply in the skills checkout. Review and validate the imported snapshot and its imports.json revision before committing and pushing skills.
Then run dot update, which fetches the latest skills main and installs the new snapshot. Each commit or push still requires user authorisation.

Background Dev Servers

Start the capture PWA dev server with mise run serve:capture and the docs dev server with mise run serve:docs. Both run through Pitchfork in the background and restart if they exit or stop responding. Do not run mise run capture:dev, mise run docs:dev, vite dev or astro dev in the foreground from an agent.
Use the :status, :logs, :restart and :stop variants of each, such as mise run serve:docs:logs, to manage them.
The daemons are configured in pitchfork.toml. Capture serves http://127.0.0.1:7490/ and docs http://127.0.0.1:7470/, or the next free port, and they are always at https://capture.notes.localhost and https://docs.notes.localhost through the Pitchfork proxy.
Test through those HTTPS addresses, in the browser, with curl and anywhere else. Never add the proxy's own port, such as :8443, even if Pitchfork prints one: that means the 443 redirect is missing (it's lost on reboot), so run pitchfork proxy doctor, then pitchfork proxy setup -y to restore it. Use the 127.0.0.1 port only when the proxy isn't running.

Validation

Run these after source changes:

mise run docs:gen
mise run check ::: build ::: docs:build

CI validates .agents/skills/ with the shared lint-agent-skills workflow.

Download now (ZIP)

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 28,693 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 repository15 other files it gives its agents.
- changeset-scopeSkill
- code-reviewSkill
- docs-kitSkill
- effect-ghSkill
- effect-herdrSkill
- effect-service-designSkill
- effectSkill
- notes-cliSkill
- notes-mcpSkill
- opentuiSkill
- skill-prefixesSkill
- task-runnersSkill
- testingSkill
- types-enforce-tsSkill
- writing-styleSkill

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