{"id":50646781,"url":"https://github.com/itsarvinddev/agent-primer","last_synced_at":"2026-06-07T13:01:45.011Z","repository":{"id":362290618,"uuid":"1256663607","full_name":"itsarvinddev/agent-primer","owner":"itsarvinddev","description":"Prime every AI coding agent at session start. One install equips Claude Code, Codex, Cursor, Gemini, opencode, Antigravity, Kimi \u0026 Qoder with curated enhancements — CodeGraph code-intelligence, the Karpathy coding guidelines, and the obra/superpowers skills plugin. Per-project or global.","archived":false,"fork":false,"pushed_at":"2026-06-03T12:27:04.000Z","size":198,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-03T14:14:56.371Z","etag":null,"topics":["agents-md","ai-coding-agents","claude-code","code-intelligence","codegraph","codex","cursor","developer-tools","gemini-cli","kimi-code","mcp","opencode","qoder","session-hooks"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/itsarvinddev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-02T01:38:41.000Z","updated_at":"2026-06-03T12:27:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/itsarvinddev/agent-primer","commit_stats":null,"previous_names":["itsarvinddev/agent-primer"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/itsarvinddev/agent-primer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itsarvinddev%2Fagent-primer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itsarvinddev%2Fagent-primer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itsarvinddev%2Fagent-primer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itsarvinddev%2Fagent-primer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/itsarvinddev","download_url":"https://codeload.github.com/itsarvinddev/agent-primer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itsarvinddev%2Fagent-primer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34022032,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-07T02:00:07.652Z","response_time":124,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents-md","ai-coding-agents","claude-code","code-intelligence","codegraph","codex","cursor","developer-tools","gemini-cli","kimi-code","mcp","opencode","qoder","session-hooks"],"created_at":"2026-06-07T13:01:43.694Z","updated_at":"2026-06-07T13:01:45.004Z","avatar_url":"https://github.com/itsarvinddev.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# agent-primer\n\nGive every AI coding agent the same good start.\n\nAgent-Primer is a small setup kit for people who use AI coding agents such as Claude Code, Codex,\nCursor, Gemini CLI, opencode, Antigravity, Kimi Code, or Qoder. It installs shared instructions and\nstartup checks so your agents begin each session with better habits: understand the codebase before\nediting, keep changes simple, verify their work, and use the right local tools.\n\nIt can be installed once for all your projects, or inside one project so a team can share the same\nagent setup.\n\n## Why Use It\n\nAI coding agents work best when they start with the right context and rules. Without that, each agent\nmay behave a little differently, forget useful tooling, or skip setup steps that would have helped it\nunderstand the code.\n\nAgent-Primer gives them a common baseline:\n\n- **CodeGraph setup**: nudges the agent to install and index the repo with CodeGraph, a local code\n  structure tool for definitions, callers, callees, traces, and impact.\n- **Careful coding habits**: asks agents to make small, focused changes, avoid guessing, and verify\n  before calling work done.\n- **Superpowers methodology**: guides agents toward systematic, test-first work and can bootstrap the\n  Superpowers skills plugin where supported.\n- **Optional Primer style memory**: learns your coding preferences locally and serves them back to\n  agents through MCP.\n\n## Quick Start\n\n### Option 1: Full Setup With Primer\n\nUse this if you want the core Agent-Primer setup plus Primer, the local coding-style memory.\n\n```bash\nnpx @agent-primer/primer setup --global\n```\n\nUse `--global` to install for all projects. Use `--project .` to install only in the current repo:\n\n```bash\nnpx @agent-primer/primer setup --project .\n```\n\nRequirement for this path: Node 22.13 or newer. The npm setup path is native Node and does not require\n`bash`; it works on Windows, macOS, and Linux.\n\n### Option 2: Core Agent-Primer Only\n\nUse this if you want the core policies and CodeGraph startup check without installing the Primer\nNode package. This path is shell-based, so it expects `bash` and preferably `python3`.\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/itsarvinddev/agent-primer/main/agent-primer.sh | bash -s -- --global\n```\n\nFor one repo only:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/itsarvinddev/agent-primer/main/agent-primer.sh | bash -s -- --project /path/to/repo\n```\n\nPrefer cloning first?\n\n```bash\ngh repo clone itsarvinddev/agent-primer ~/.agent-primer-src\n~/.agent-primer-src/install.sh --global\n```\n\nAfter either install path, restart your agent or IDE so the new hooks and MCP tools can load.\n\n## Let Your Agent Install It\n\nIf you are already inside an AI coding agent, you can paste this:\n\n\u003e Install agent-primer from https://github.com/itsarvinddev/agent-primer. Use the global install:\n\u003e `curl -fsSL https://raw.githubusercontent.com/itsarvinddev/agent-primer/main/agent-primer.sh | bash -s -- --global`.\n\u003e Tell me what files you changed and remind me to restart this agent or IDE afterward.\n\nThe agent should announce commands before running them, because installation changes files on your\nmachine.\n\n## What Happens During Setup\n\nAgent-Primer adds marked instruction blocks, and where an agent supports them, startup hooks. The\ninstaller is idempotent, so running it again updates the same blocks instead of duplicating them.\n\nAt session start, the CodeGraph hook checks whether the project is ready:\n\n```text\nsession starts\n  -\u003e is the codegraph CLI installed?\n  -\u003e is this project indexed with .codegraph/?\n  -\u003e if setup is missing, show the agent exactly what to run\n  -\u003e if setup is done, stay quiet\n```\n\nThe hook is read-only and exits successfully. It does not block your agent. Once a project has a\n`.codegraph/` index, the hook becomes quiet by default.\n\nIf you installed Primer, Agent-Primer also wires a local style-memory loop:\n\n```text\nsession starts\n  -\u003e Primer injects a short style brief\nagent edits code\n  -\u003e safe edit signals can be captured locally\nagent learns later\n  -\u003e durable preferences are recorded in .primer/ or ~/.primer/\n```\n\nPrimer has no cloud service, no bundled model, no telemetry, and no network sync. The user's own\nagent does any learning work from local signals.\n\n## Day-To-Day Use\n\nAfter setup, use your coding agent normally.\n\nOn a new repo, the agent may ask to initialize CodeGraph:\n\n```bash\ncodegraph init -i\n```\n\nIf the CodeGraph MCP tools are not available yet, restart the agent or IDE. Until then, the\n`codegraph` command-line tool can still be used directly.\n\nIf Primer is installed, you can record preferences yourself:\n\n```bash\nprimer record --category testing --statement \"Use vitest for unit tests\" --language typescript\nprimer show\nprimer status\n```\n\nAgents can also use Primer's MCP tools after restart:\n\n- `primer_apply` asks for relevant style preferences before editing.\n- `primer_record` stores a durable preference you stated or demonstrated.\n- `primer_query` searches saved preferences.\n- `primer_learn` turns recent local edit signals into candidate preferences.\n- `primer_impact` explains which style facts or preferences relate to a file.\n- `primer_status` reports local style-memory health.\n\n## Install Options\n\nCommon examples:\n\n```bash\n# Install for all supported agents and all projects\n./install.sh --global\n\n# Install inside one project\n./install.sh --project .\n\n# Install only for selected agents\n./install.sh --global --agents claude,codex,cursor\n\n# Preview changes without writing files\n./install.sh --global --dry-run\n\n# Add optional bundles\n./install.sh --global --with mcp,rules\n\n# Add Primer when using the bash installer\n./install.sh --global --with primer\n```\n\nAvailable optional bundles:\n\n| Bundle | What it adds |\n|---|---|\n| `mcp` | Recommended MCP servers such as Context7, GitHub, and Playwright |\n| `tools` | Helpful CLI tools such as ast-grep and repomix |\n| `rules` | Security, 12-Factor Agents, and commit/PR hygiene guidance |\n| `skills` | Extra public skill registries |\n| `agent-extensions` | Agent-specific extension and plugin guidance |\n| `primer` | The local Primer coding-style engine; requires Node 22.13 or newer |\n\n`--with all` installs the general optional bundles, but not `primer`. Primer is separate because it\nhas a Node requirement.\n\n## Supported Agents\n\n| Agent | What Agent-Primer can wire |\n|---|---|\n| Claude Code | Instructions, rules, hooks, MCP setup |\n| Codex | `AGENTS.md`, hooks, MCP setup |\n| Cursor | `AGENTS.md`, Cursor rules, hooks, MCP setup |\n| Gemini CLI | `GEMINI.md`, hooks, MCP setup |\n| opencode | `AGENTS.md`, plugin hook, MCP setup |\n| Antigravity | `AGENTS.md`, rules, hooks |\n| Kimi Code | Skills and global hook support |\n| Qoder | Rules and instructions; no SessionStart hook |\n\nExact file locations differ by global vs project install, but the installer prints what it writes.\n\n## Uninstall\n\nRemove the global setup:\n\n```bash\n./uninstall.sh --global\n```\n\nRemove a project setup:\n\n```bash\n./uninstall.sh --project /path/to/repo\n```\n\nIf you installed through `npx`, you can also run:\n\n```bash\nnpx @agent-primer/primer teardown --global\n```\n\nUninstall removes Agent-Primer's wiring. It does not remove tools you may use elsewhere, such as the\nCodeGraph CLI. Primer's learned style database is kept by default; pass `--purge` if you want to\ndelete it too.\n\n## Files In This Repo\n\n| Path | Purpose |\n|---|---|\n| `install.sh` | Main installer |\n| `uninstall.sh` | Reverses an install |\n| `agent-primer.sh` | Single-file portable installer |\n| `make-portable.sh` | Regenerates `agent-primer.sh` after edits |\n| `codegraph-session-check.sh` | Safe session-start check for CodeGraph |\n| `*-policy.md` | Instruction blocks copied into agent config files |\n| `primer/` | The Primer npm package and local style-memory engine |\n| `tests/smoke.sh` | Install/uninstall smoke tests |\n\n## Development\n\n```bash\n./tests/smoke.sh\n./make-portable.sh\n\ncd primer\nnpm ci\nnpm test\n```\n\nIf you change the installer, policy files, or hook script, run `./make-portable.sh` so\n`agent-primer.sh` stays in sync.\n\n## Privacy\n\nAgent-Primer itself is a local installer. Primer, when enabled, stores its database in `.primer/` for\na project or `~/.primer/` globally. It skips common secret, dependency, build, and generated files,\nscrubs secret-looking excerpts, and does not send anything to a server.\n\n## Credits\n\nAgent-Primer wires helpful upstream projects into your agents. It does not replace them:\n\n- [CodeGraph](https://github.com/colbymchenry/codegraph) for local code-structure indexing.\n- [Superpowers](https://github.com/obra/superpowers) for the skills plugin and methodology.\n- The Karpathy coding guidelines adapted from\n  [multica-ai/andrej-karpathy-skills](https://github.com/multica-ai/andrej-karpathy-skills).\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitsarvinddev%2Fagent-primer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fitsarvinddev%2Fagent-primer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitsarvinddev%2Fagent-primer/lists"}