Acharya — a disciplined AI dev team for your codebase

Acharya turns Claude Code into a managed team of specialist engineers for your repo — a lead who analyzes and asks before acting, one cheap "hands" agent that types, an independent reviewer who never saw the code being written, and stack specialists (SQL, analytics, queues) that remove themselves if your stack doesn't need them.

It's a single .claude/ folder. Copy it in, run one command, and it adapts itself to your codebase.

⚠️ For complex, multi-feature projects only. Acharya's value is discipline at scale — many feature areas, shared datastores, background jobs. On a small project (a script, a weekend prototype) this workflow is pure overhead; plain Claude Code will be faster and cheaper.

Quick start (60 seconds)

cd your-repo          # your project's root
npx acharya init      # scaffolds the .claude/ folder here

Then open Claude Code in the repo and run:

/acharya-init

That's it. This one command detects your stack, asks you to confirm names/paths, deletes the specialist agents your stack doesn't need, and generates a skills knowledge base for your codebase. From the next session on, Acharya greets you as your lead engineer.

How the npm install works (important): the package is only an installer. npx acharya init copies .claude/ out of the package and into your repo root as plain files that you own and commit to your git — like create-vite scaffolding a project. Nothing stays in node_modules, nothing is added to your package.json, and Claude Code never reads from node_modules. If you ever run npm install acharya as a dependency instead — harmless, but nothing happens until you run the init.

Other commands: npx acharya init --dry-run (preview, writes nothing) · init --force (update kit files; your skills/config/local settings are preserved) · npx acharya doctor (health-check an installed kit).

Requirements: Claude Code · Node ≥ 18 · any git host (GitHub, GitLab, Bitbucket — the kit uses plain git only).

New to Claude Code kits? The vocabulary, in 30 seconds

| Term | What it actually is | |---|---| | .claude/ folder | Where a repo's Claude Code configuration lives. This whole kit is that one folder. | | Agent (subagent) | A specialist Claude with its own instructions and tool permissions, spawned for one job (e.g. "review this diff") and gone when done. Defined as markdown files in .claude/agents/. | | Slash command | A saved workflow you trigger by typing /name in Claude Code (e.g. /bug). Defined in .claude/commands/. Think of them as runbooks the AI follows. | | Hook | A script Claude Code runs automatically at lifecycle events — e.g. on session start, or every time you submit a prompt. Wired in .claude/settings.json. Hooks are how this kit loads its persona and nudges you to the right command, without you doing anything. | | Skill | A markdown knowledge file about ONE feature area of your codebase (e.g. auth, billing, mysql-schema): where it lives, its invariants, its gotchas. Skills are the kit's long-term memory — agents read them instead of re-scanning your code every session. | | Identity / persona | The character and standing rules of the lead engineer (identity.md). Loaded by a hook at every session start. | | Contract | The rulebook every agent follows (contract.md): who decides what, when to ask you, when to spawn agents, how to spend tokens. | | Permissions | An allow/ask list in settings.json controlling what the AI may run. This kit pre-allows safe read-only git commands — and forces a prompt on git push. |

What's in the box

.claude/
├── identity.md            the persona + its standing rules (template, auto-filled per project)
├── contract.md            the rulebook: 4-phase workflow, token tiers, code style, git safety
├── acharya.config.json    ⭐ THE one file you edit — names, stack, datastores, agent codenames
├── settings.json          hook wiring + safe permissions (git push always prompts)
├── agents/                14 specialist agents (markdown definitions)
├── commands/              10 slash commands — the workflows
├── scripts/               the hooks + helpers (plain Node/bash, zero dependencies)
├── skills/                YOUR codebase's knowledge base — generated by /acharya-init
└── skills-routing.json    map of "which files belong to which skill"

Meet the guild

One persona leads. Specialists are called by routing id; the Vedic codenames are pure flavour — re-theme them in the config.

| Routing id | Codename | What it does | |---|---|---| | — (main thread) | Acharya | your lead engineer; does most work itself, delegates only when it pays | | feature | Brahma — the Creator | plans new full-stack features | | bug | Rudra — the Destroyer | minimal-scope bug fixes, root cause first | | extend | Vishnu — the Preserver | extends existing surfaces, maps every caller | | review | Netra — the All-Seeing Eye | independent reviewer — logic, security, blast radius, future risks | | editor | Shilpi — the Craftsman | the single "hands" agent for batch edits, runs on a cheap model | | explorer | Pathik — the Wayfarer | read-only navigator; returns file:line maps, not file dumps | | precommit | Dwarpal — the Gatekeeper | fast lint / type / skill-drift gate before commits | | release-notes | Vyasa — the Chronicler | changelogs grouped by feature area | | skill-maintainer | Guru — the Keeper | creates and refreshes the skills | | skill-updater | Lipi — the Scribe | minimal skill sync for small diffs | | migration | Setu — the Bridge | DB schema migrations — designs, never executes | | mysql-query-builder | Lekha — the Archivist | index-aware MySQL query design | | clickhouse-query-builder | Kala — the Timekeeper | sorting-key-aware ClickHouse query design | | redis-queue-engineer | Vayu — the Windrunner | BullMQ/Redis queues, workers, cache keys |

The last four are stack specialists — /acharya-init deletes the ones your datastores config doesn't justify, and the roster shown at session start updates automatically.

How work flows — the 4-phase contract

The core principle: the AI analyzes; the developer decides. Scope, design trade-offs, and edge-case handling are yours to pick — at ONE batched checkpoint, not a drip of questions.

1. ANALYZE  ─►  2. ASK (once)  ─►  3. IMPLEMENT  ─►  4. REVIEW
  (read code     (ONE batched       (inline by       (independent agent,
   + skills)      decision round)    default)         once, on the final diff)

• Phase 4 is independent by construction — the reviewer didn't write the code, so it doesn't inherit the author's blind spots. Findings come back as checkboxes: fix now / ticket / accept.
• Risky boundaries (auth, payments, migrations, data writes) get the independent review regardless of diff size.
• When there's only one sane answer, the checkpoint is skipped and the assumption stated in one line — ceremony is not the point.

And one rule is absolute: the kit never pushes on its own. The contract forbids it, the persona carries it as a reflex, and settings.json forces a permission prompt on every git push. Commits are drafted and confirmed; pushes are always yours.

What a session looks like

> we need rate limiting on the public API

Acharya: Standard tier (~15k). Reading the api-gateway + auth skills…

── Phase 2: one batched checkpoint ────────────────────────────────
  Scope?       ( ) Minimal — per-route guard
               (•) Extensible — middleware + config table
  Design?      (•) reuse existing redis client   ( ) new limiter module
  Edge cases?  [x] burst on login   [ ] internal service calls
────────────────────────────────────────── you pick, Acharya builds ──

Acharya: Done — 4 files, +182 −7. Firing Netra (independent review)…

NETRA — FINDINGS
  HIGH  gateway.js:84  limit key derives from user-id BEFORE auth →
        unauthenticated requests all share one bucket.
  CROSS_IMPACT  webhooks → shares the middleware chain → AT_RISK

Fix now, ticket, or accept? — one batch, you decide.

The slash commands

| Command | When you use it | |---|---| | /acharya-init | Once, after install — adapts the kit to this repo and generates skills | | /triage | Not sure which command fits? This routes you (also auto-suggested by a hook) | | /feature <spec> | Build a new feature (full 4-phase flow) | | /bug <report> | Fix a bug — root cause first, minimal diff | | /extend <change> | Extend an existing surface — maps all callers first | | /migration <change> | DB schema change — writes forward + rollback SQL, never executes | | /review | Independent review of the current diff | | /commit | Drafts a conventional commit + Affected-skills: footer, asks, commits | | /update-skills | Re-syncs skills after code changed | | /release-notes <range> | Changelog grouped by feature area |

Why it's cheap to run

Multi-agent setups usually die by billing. Acharya is built around one number: a subagent hop costs ~15× an inline pass — so the contract enforces altitude discipline:

| Tier | Fits | Budget | |---|---|---| | Lean | 1–2 file fix | ≤ 5k tokens, no subagents | | Standard | routine feature/bug | ~10–30k, inline, one ASK, one review | | Heavy | audits, migrations, sweeps | 30k+, declared up front — parallelism actually pays here |

The tier is announced at task start so you see the spend before it's burned. Other rules: agents only for parallelism / context isolation / independence, one cheap writer for batch edits, decisions batched into one round, review once on the final diff — and skills instead of re-reading, which is the biggest saving: the kit remembers your codebase between sessions instead of re-deriving it.

Which agent runs on which model — and why

Every agent pins the cheapest Claude model that is safe for its job. The principle: cost follows consequence — pay for intelligence only where a wrong-but-plausible answer is expensive, and never pay for reasoning where there's nothing to decide.

| Model | Agents | Why this tier | |---|---|---| | Haiku (cheapest, fastest) | editor (Shilpi) · precommit (Dwarpal) | Pure mechanical work. The editor receives a finished patch spec — every decision was already made by a planner — so it just types. Precommit runs lint/type/drift gates. Zero design choices → zero reason to pay for reasoning. | | Sonnet (mid) | feature / bug / extend planners · explorer · migration · redis-queue-engineer · release-notes · skill-updater | Structured reasoning on rails: the contract dictates their phases, the skills hand them the hard-won context, and checklists constrain their output. They need competence, not genius — the guardrails do the heavy lifting. | | Opus (strongest) | review (Netra) · mysql-query-builder (Lekha) · clickhouse-query-builder (Kala) · skill-maintainer (Guru) | The seats where a plausible-looking mistake is the most expensive thing in the system: a missed bug ships to production; a wrong index melts a hot table; a subtly wrong skill poisons every future session that trusts it. Here the model cost is noise next to the error cost. | | (your session model) | the main thread — Acharya itself | Inherits whatever you chose for your session. The kit never silently upgrades your spend; it economizes on the agents it spawns, not on you. |

Two deliberate asymmetries worth noticing:

• The thinking/typing split. Planners reason on Sonnet, then hand a spec to the Haiku editor. You pay reasoning prices for reasoning and typing prices for typing — never reasoning prices for typing.
• The reviewer outranks the builders. Work is built on Sonnet but reviewed on Opus. Cheap to write, expensive to judge — because the judge is the last line before your codebase, and a reviewer that rubber-stamps is worse than no reviewer at all.

Skills stay honest through tooling: every commit gets an Affected-skills: footer, a sync marker tracks the last commit skills were updated for, and /update-skills (or npx acharya doctor) tells you when they've drifted.

Customizing

Everything project-specific lives in acharya.config.json: the assistant's name, what it calls you, your stack and datastores (this drives specialist pruning), and every codename. The prose personality lives in identity.md. Nothing else needs touching.

FAQ

Where does the kit "run" from? Your repo root. The npm package is just the courier — after init you own the files, commit them, and your whole team gets the same setup on clone.

Does it need GitHub? No. Plain git only — GitHub, GitLab, Bitbucket, or a bare remote all work the same.

Can it push/deploy something by itself? No. git push is permission-gated and contractually requires your explicit go-ahead, every time.

My project is small — should I use this? Honestly: no. That's not modesty, it's the kit's own contract talking — process has a cost, and below a certain complexity the cost exceeds the value.

I work across two repos that share a database — is that covered? That's a different hazard class (double-firing crons, shared queues). See Kira — the cross-repo bridge built on this kit.

License

MIT