FAQ

Common questions about clarc.

Installation

How do I install clarc?

npx github:marvinrichter/clarc typescript   # or python, go, swift, java, ...

Why npx github:marvinrichter/clarc and not npx clarc?

The GitHub-direct install is intentional. It eliminates the npm registry as an attack vector (supply chain security). npx github:... clones directly from the verified source — no intermediary.

How do I check if clarc is installed correctly?

npx github:marvinrichter/clarc doctor
# or in Claude Code: /doctor

How do I update clarc?

cd ~/.clarc && git pull

Symlinks update instantly. No re-install needed.

Can I install for multiple languages?

npx github:marvinrichter/clarc typescript python go

Using clarc

Where do I start?

Run /quickstart in Claude Code for a guided tour. Or run /clarc-way for a recommendation based on your current task.

I have too many commands. Which ones should I actually use?

The 5 most impactful:

Do I need to run every command manually?

No. Most agents activate automatically. code-reviewer runs after you write code, security-reviewer when you touch auth/APIs, build-error-resolver when the build fails. You don't have to invoke them — clarc does it.

What's the difference between agents and skills?

• Agents are Claude subagents that do work (plan, review, test, build).
• Skills are knowledge files that Claude reads to understand a domain (TypeScript patterns, PostgreSQL optimization, the clarc Way methodology).

Agents act. Skills inform.

Can I create my own agents and skills?

Yes. Add them to ~/.claude/agents/ or ~/.claude/skills/. clarc's installer never overwrites files that already exist there. Use /skill-create to generate a skill from your project's git history.

Methodology

Do I have to follow The clarc Way?

No. Skip phases that don't apply. A bug fix doesn't need /idea and /evaluate. A chore doesn't need /tdd. The skip matrix in The clarc Way tells you what to skip.

What's the difference between clarc and SPARC?

Both are structured AI development methodologies. clarc is more tooling-integrated — every phase has dedicated commands and agents. clarc also has a continuous learning loop (instincts → skills) that improves the system over time. See the comparison table in The clarc Way skill.

Why test-first? Can I write implementation before tests?

You can, but clarc won't auto-validate it. TDD is the quality gate. A test written after implementation doesn't prove the code is correct — it proves the implementation and test are consistent. Writing the test first forces you to define the expected behavior before you're influenced by how you happened to implement it.

Hooks & Automation

What do hooks do?

Hooks run automatically at specific events:

• Auto-checkpoint: saves a git snapshot after every file edit (enables /undo)
• Session start: loads the session context, detects your package manager
• Session end: saves session state, triggers weekly instinct digest
• Auto-format: formats code after edits (language-specific)

My hooks aren't running. What's wrong?

Run /doctor — it checks hooks.json validity. Common causes:

• hooks.json has a JSON syntax error
• The hooks directory isn't in the right location (~/.claude/hooks/)

Contributing

How do I contribute a skill or agent?

See CONTRIBUTING.md. Skills are Markdown files in skills/<name>/SKILL.md. Agents are Markdown files with YAML frontmatter in agents/<name>.md. Open a PR with your addition.

I found a bug. Where do I report it?

GitHub Issues. For questions, use GitHub Discussions.

Continuous Learning

What is the learning loop?

clarc observes patterns across your sessions and captures them as "instincts" — structured observations with a confidence score. Over time, high-confidence instincts get promoted into skills and agent overlays that make clarc smarter for your specific workflow.

The cycle: observe → capture → promote → apply

• /learn-eval — extract reusable patterns from the current session
• /instinct-status — view all captured instincts and confidence scores
• /evolve — cluster instincts into new permanent skills
• /agent-evolution — promote instincts directly into agent instructions

What are agent instincts?

Agent instincts are learned behaviors attached to a specific agent. When confidence is high enough (≥ 0.75 by default), an instinct is promoted to an overlay file in ~/.clarc/agent-instincts/<agent>.md. At session start, clarc injects those overlays into Claude's context — the agent applies them automatically without any manual invocation.

Example: if the typescript-reviewer repeatedly catches the same pattern (e.g., missing error boundaries), that becomes an instinct and is injected on every future review.

Does the learning loop affect other users?

No. Instincts and overlays are stored in ~/.clarc/ — they're user-local and never committed to the repo. Your learned patterns stay private.

How do I roll back a bad instinct?

/instinct-outcome <id> bad --reason "Made agent too aggressive"

The confidence score drops below the promotion threshold. Run /agent-evolution to confirm removal from the overlay.