https://github.com/marvinrichter/clarc
Production-grade Claude Code workflow OS — agents, skills, hooks, commands, rules, and a continuous learning flywheel.
https://github.com/marvinrichter/clarc
ai-agents claude claude-code cli developer-tools llm productivity workflow
Last synced: 3 months ago
JSON representation
Production-grade Claude Code workflow OS — agents, skills, hooks, commands, rules, and a continuous learning flywheel.
- Host: GitHub
- URL: https://github.com/marvinrichter/clarc
- Owner: marvinrichter
- License: mit
- Created: 2026-03-06T21:31:16.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-03-20T07:37:34.000Z (3 months ago)
- Last Synced: 2026-03-20T07:43:39.609Z (3 months ago)
- Topics: ai-agents, claude, claude-code, cli, developer-tools, llm, productivity, workflow
- Language: JavaScript
- Homepage: https://marvinrichter.github.io/clarc
- Size: 18.6 MB
- Stars: 5
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Roadmap: docs/roadmaps/ROADMAP.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# clarc
**The workflow OS for Claude Code.**
63 agents · 249 skills · 178 commands · 20 language rule sets · continuous learning flywheel.
[](https://github.com/marvinrichter/clarc/actions/workflows/ci.yml)
[](LICENSE)
[](https://nodejs.org)
---
clarc turns Claude Code from a coding assistant into a structured engineering system. It brings together agents that delegate work, skills that encode domain knowledge, commands that run repeatable workflows, hooks that automate the background, and a learning loop that improves itself over time.
---
## The clarc Way
clarc ships a complete, opinionated development methodology — from raw idea to shipped code.
```
Phase 0: Discovery /idea → /evaluate → /explore → /prd
Phase 1: Planning /plan
Phase 2: Implementation /tdd (RED → GREEN → IMPROVE)
Phase 3: Quality /code-review + /security
Phase 4: Ship /commit-push-pr
```
**Skip what you don't need:**
| Task | Start here |
|------|-----------|
| New idea (unsure if worth building) | `/idea` |
| Feature with clear spec | `/plan` |
| Bug fix | `/tdd` (write the failing test first) |
| Refactor | `/plan` → `/tdd` |
| Docs / chore | `/commit` |
Run `/clarc-way` to get a tailored recommendation for your current task.
Run `/quickstart` if you're new to clarc.
---
## Getting Started in 5 Minutes
```bash
# 1. Install (pick your language)
npx github:marvinrichter/clarc typescript
npx github:marvinrichter/clarc python
npx github:marvinrichter/clarc go
# 2. Verify the installation
npx github:marvinrichter/clarc doctor
# 3. Open Claude Code and run your first command
# /quickstart → guided tour of the most important workflows
# /clarc-way → what to do for your current task
```
---
## Install
```bash
# Recommended — interactive wizard (auto-detects your languages)
npx github:marvinrichter/clarc
# Or with explicit language(s) — skips the wizard
npx github:marvinrichter/clarc typescript
npx github:marvinrichter/clarc typescript python go
# Other editors
npx github:marvinrichter/clarc --target cursor typescript
npx github:marvinrichter/clarc --target opencode typescript
npx github:marvinrichter/clarc --target codex
# Check if your installed rules are up to date
npx github:marvinrichter/clarc --check
```
The wizard clones clarc to `~/.clarc/` on first run, then **symlinks** agents, commands, and rules into `~/.claude/`. A single `git pull` in `~/.clarc/` keeps everything current — no re-install needed.
```
~/.claude/agents/tdd-guide.md → ~/.clarc/agents/tdd-guide.md (symlink)
~/.claude/commands/plan.md → ~/.clarc/commands/plan.md (symlink)
~/.claude/rules/common/*.md → ~/.clarc/rules/common/*.md (symlinks)
```
Your own agents or rules placed in `~/.claude/agents/` or `~/.claude/rules/` are never touched — symlinks only fill in files that don't already exist there.
```bash
# Update clarc
cd ~/.clarc && git pull
# Force copy instead of symlinks (CI, containers, cross-filesystem)
npx github:marvinrichter/clarc --copy typescript
```
Clone and run locally
```bash
git clone git@github.com:marvinrichter/clarc.git ~/.clarc
~/.clarc/install.sh typescript
~/.clarc/install.sh --enable-learning typescript
~/.clarc/install.sh --check
```
---
## What's inside
| Component | Count | Purpose |
|-----------|------:|---------|
| **Agents** | 63 | Specialized subagents — delegate planning, review, testing, debugging |
| **Skills** | 249 | Domain knowledge — patterns, conventions, examples for specific tasks |
| **Commands** | 178 | Slash commands — repeatable workflows triggered by `/command` |
| **Rules** | 20 | Language rule sets — always-on coding standards and checklists |
| **Hooks** | — | Background automations — format, lint, persist state, weekly digests |
---
## Agents
Agents are delegated automatically based on what you're doing. You can also invoke them explicitly.
| Agent | When it activates |
|-------|------------------|
| `planner` | Complex features, refactoring, anything requiring a plan first |
| `tdd-guide` | New features and bug fixes — enforces write-tests-first |
| `code-reviewer` | Immediately after writing or modifying code |
| `security-reviewer` | Before commits touching auth, input handling, secrets |
| `architect` | Architectural decisions, ADR creation |
| `build-error-resolver` | When the build fails |
| `typescript-reviewer` | TypeScript-specific patterns and type safety |
| `python-reviewer` | Python idioms, PEP 8, async patterns |
| `go-reviewer` | Idiomatic Go, error handling, goroutine patterns |
| `java-reviewer` | Spring Boot, JPA, hexagonal architecture |
| `swift-reviewer` | SwiftUI, Combine, concurrency |
| `ruby-reviewer` | Idiomatic Ruby, Rails best practices, RuboCop |
| `elixir-reviewer` | OTP patterns, Ecto, Phoenix context violations |
| `product-evaluator` | Go/No-Go evaluation of new feature ideas |
| `solution-designer` | Generates 2–4 solution options with trade-off analysis |
| `refactor-cleaner` | Identifies and removes dead code safely |
| `doc-updater` | Keeps documentation in sync with code changes |
| `android-reviewer` | Jetpack Compose, Hilt scopes, Room migrations, Coroutines |
| `gitops-architect` | Designs GitOps setup — ArgoCD/Flux, env strategy, progressive delivery |
| `finops-advisor` | Cloud cost analysis, rightsizing, ROI-prioritized recommendations |
| `devsecops-reviewer` | SAST, secrets detection, IaC misconfigurations, OWASP Top 10 |
| `mlops-architect` | ML serving stack, monitoring, drift detection, A/B testing plans |
| `sdk-architect` | SDK architecture, multi-language generation, release process |
| `frontend-architect` | Micro-frontend architecture, Module Federation, team topology |
| `data-architect` | Data Mesh design, domain products, migration from monolith |
| `docs-architect` | API documentation strategy, Mintlify/Docusaurus, Divio structure |
---
## Key commands
### Daily workflow
```
/clarc-way Interactive guide — recommends the right workflow for your task
/quickstart First-time onboarding — understand clarc in 5 minutes
/plan Plan implementation before writing code
/tdd Enforce test-first development
/code-review Security and quality review
/verify Full build, type check, lint, test cycle
/build-fix Incrementally fix build and type errors
```
### Product & architecture
```
/idea Capture and structure a raw product idea
/evaluate Go/No-Go evaluation before building
/prd Write a Product Requirements Document
/explore Generate and compare solution options
/breakdown Break a feature into sprint-ready user stories
/adr Record an Architecture Decision
/arc42 Generate or update arc42 architecture documentation
```
### Engineering operations
```
/slo Define SLIs, SLOs, and error budget alerts
/instrument Add analytics event tracking to code
/experiment Design a statistically valid A/B test
/incident Open and manage a production incident
/deps Dependency audit and upgrade planner
/setup-ci Generate GitHub Actions CI/CD pipeline
/security Full DevSecOps scan — SAST, secrets, deps, DAST, OPA
/gitops-review Review GitOps config — sync, secrets, drift, progressive delivery
/finops-audit Cloud cost audit — tagging, rightsizing, anomalies, Infracost
/zero-trust-review Service mesh & mTLS review — identity, NetworkPolicies, east-west
/iac-review IaC code review — Pulumi/CDK/Terraform abstractions, compliance
/mlops-review MLOps audit — experiment tracking, serving, drift detection
/privacy-audit Privacy engineering audit — PII scan, retention, RTBF, consent
/android-review Android/Compose review — UDF, Hilt, Room, Coroutines
/mobile-release Mobile release workflow — signing, beta, store submission
/webrtc-review WebRTC architecture review — TURN, signaling, simulcast, security
/frontend-arch-review Micro-frontend architecture review — federation, routing, DX
/data-mesh-review Data Mesh review — domain boundaries, contracts, quality, lineage
/sdk-review SDK design review — ergonomics, backward compat, error design
/docs-review API documentation audit — completeness, playground, changelog
/onboard Generate onboarding materials — CONTRIBUTING.md, architecture tour
```
### Learning & evolution
```
/learn-eval Extract reusable patterns with quality gate + save-location decision
/evolve Promote instincts into permanent skills
/instinct-status Show what the system has learned
/sessions Browse session history and snapshots
```
---
## Skills
Skills are loaded on-demand when Claude detects they're relevant. They encode domain knowledge in a structured format: when to use, patterns, examples, anti-patterns.
**Language patterns:** TypeScript · Python · Go · Java · Rust · Swift · C++ · Ruby · Elixir · Django · Spring Boot · React Native · SwiftUI · Android/Jetpack Compose · Flutter · WebAssembly · Kotlin · Scala · PHP · R · C# · Bash
**Architecture:** Hexagonal · DDD · Strategic DDD · API design · gRPC · GraphQL · WebSockets · Micro-Frontends/Module Federation · Zero-Trust/Service Mesh · Data Mesh · CQRS/Event Sourcing · Multi-Agent Systems
**Data:** PostgreSQL · DuckDB · NoSQL · Redis/caching · database migrations · Data Mesh (Great Expectations, Soda, Delta Lake, Iceberg)
**Infrastructure:** Terraform · Pulumi · AWS/Azure CDK · Kubernetes · Docker · GitOps (ArgoCD, Flux) · FinOps (Infracost, OpenCost) · CI/CD · deployment patterns · Edge/Serverless
**Testing:** TDD workflow · E2E (Playwright) · contract testing (Pact) · visual regression · load testing · eval harness · chaos engineering · MLOps (A/B model testing, drift detection)
**Security:** DevSecOps (SAST/DAST, OPA/Kyverno) · supply chain (SBOM/SLSA) · privacy engineering (PII, Presidio) · GDPR · auth patterns · Zero-Trust
**AI/ML:** LLM app patterns · RAG · eval harness · MLOps · cost-aware pipelines · foundation models · prompt engineering · SDK design
**Ops:** Observability · SLO workflow · incident response · performance profiling · platform engineering · developer onboarding
**Product engineering:** Analytics workflow · experiment design · feature flags · A/B testing · compliance & audit logs · API documentation engineering
**Team process:** OKRs · sprint planning · DORA metrics · roadmapping · working agreements
---
## Continuous learning flywheel
clarc gets better the more you use it. There are two learning mechanisms:
**Session learning** (`/learn-eval`)
At the end of a session, extracts recurring patterns, friction points, and solved problems into instinct files — with a quality gate and save-location decision (global vs. project-scoped) before writing. These become part of your personal context in future sessions.
**Instinct evolution** (`/evolve`)
Analyzes accumulated instincts and promotes stable, high-signal ones into permanent skills. Closes the loop from observation → codified knowledge.
**Weekly evolve batch**
Every Monday, clarc automatically analyzes accumulated instincts and generates a digest with promotion suggestions — without waiting for a manual `/evolve` call.
**Conflict detection**
When contradictory instincts exist in the same domain (e.g. "prefer functional" vs "use classes"), they are flagged in `conflicts.json` and surfaced in `/instinct-status` for resolution.
**Pre-compact snapshots**
Before context compaction, clarc reads the session transcript and persists a structured snapshot: open tasks, touched files, recent exchanges. Nothing is lost between context resets.
---
## Language rules
Rules are guidelines that complement skills: rules define *what* to do, skills show *how*. `common/` rules are always active. Language rules activate automatically when you open files of that type (via `globs:` frontmatter) — they don't add overhead for projects that don't use them.
**Performance tip:** install only the language sets you need to keep context lean.
```
rules/
├── common/ # Universal — immutability, error handling, security, GitOps, onboarding
├── typescript/ # TS/JS — strict typing, ESM, React patterns
├── python/ # PEP 8, type hints, async idioms
├── go/ # Idiomatic Go, error wrapping, goroutines
├── swift/ # Swift 6, actors, value types
├── java/ # Spring Boot, JPA, hexagonal architecture
├── rust/ # Ownership, Result/Option, unsafe rules
├── cpp/ # C++17/20, RAII, smart pointers
├── ruby/ # RuboCop, Rails conventions, RSpec, Brakeman
├── elixir/ # mix format, Credo, OTP patterns, Sobelow
├── kotlin/ # Coroutines, null safety, sealed classes
├── bash/ # set -euo pipefail, quoting, shellcheck
├── scala/ # Functional idioms, ADTs, effect systems
├── c/ # C11/C17, memory safety, opaque pointers
├── php/ # PHP 8.4+, strict types, PSR-12
├── r/ # tidyverse, native pipe, renv
├── csharp/ # C# 12/.NET 8, nullable, records
├── sql/ # Query optimization, indexing, migrations
├── flutter/ # Widget lifecycle, state management, null safety
└── android/ # Compose UDF, Hilt scopes, Room, Coroutines
```
---
## Multi-editor support
clarc ships configurations for multiple editors alongside the primary Claude Code integration:
- **Claude Code** — agents, skills, commands, hooks, rules (full support)
- **Cursor** — 96 language rules in `.cursor/rules/` + `.cursorrules` global config (`--target cursor`)
- **OpenCode** — 65 commands + agent prompts under `.opencode/` (`--target opencode`)
- **Codex CLI** — instructions + 14 commands under `codex/` (`--target codex`)
### clarc as MCP server
clarc can expose its own state as an MCP server, letting subagents and external tools query it directly:
```json
{ "mcpServers": { "clarc": { "command": "node", "args": ["/mcp-server/index.js"] } } }
```
Available tools: `get_instinct_status` · `get_session_context` · `get_project_context` · `skill_search` · `agent_describe` · `rule_check` · `get_component_graph` · `get_health_status`
---
## Structure
```
clarc/
├── agents/ # Subagent definitions (frontmatter + instructions)
├── skills/ # Domain knowledge skills (SKILL.md per topic)
├── skills/INDEX.md # Machine-readable skill catalog by domain
├── commands/ # Slash commands (/tdd, /plan, /breakdown, ...)
├── hooks/ # Hook configurations (JSON)
├── scripts/hooks/ # Hook implementations (Node.js)
├── rules/ # Language rule sets (20 languages)
├── mcp-configs/ # MCP server configurations
├── mcp-server/ # clarc as an MCP server (8 tools)
├── .opencode/ # OpenCode commands and agent prompts
├── .cursor/ # Cursor rules (50+ language rule files)
├── codex/ # Codex CLI instructions and commands
├── tests/ # Structural evals, behavior evals, unit tests
└── install.sh # Installer: --check, --target cursor/opencode/codex, --enable-learning
```
---
## Based on
clarc is a heavily extended fork of [everything-claude-code](https://github.com/affaan-m/everything-claude-code) by Affaan Mustafa, released under the MIT License.