convez.ai
Skill
SideMountain

claude-code-sidekick

SideMountain/claude-code-sidekick

Ver no GitHub
InicialPluginScore · de 0 a 100

Claude Code harness template — safety hooks, reusable skills, and a learning memory

Instalação

$npx convez-ai SideMountain/claude-code-sidekick

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 3 meses
Versão
v0.18.0
Issues abertas
16
Contribuidores
2

README

A tradução para o português deste README ainda está na fila.

sidekick

Teach Claude Code your decision-making. Then hand off.

日本語版 README はこちら

MIT License Claude Code Status

A repository template that makes Claude Code safe, personalized, and autonomous. Read it top to bottom: what it is → the loop you run → how it works under the hood.


In 30 seconds

sidekick is a repository template for Claude Code. It ships with three layers built in:

🛡️ Safety Guards🧰 Reusable Workflows🧠 Thinking OS
Physically blocks dangerous ops like rm -rf or pushing to main17 skills ready to use: /discover, /review, /auto-implement, etc.Learns your decision principles — Claude's proposals improve over time

The "Thinking OS" is what sets sidekick apart from other templates.


The loop you actually run

Day to day, you only touch three verbs. Everything else is plumbing that fires on its own — you don't memorize it.

flowchart LR
    N["① /news<br/>catch up on<br/>what changed"] --> W["② your work<br/>Claude handles worktree,<br/>scoped tests, /review, PR"]
    W --> C["③ /close-chat<br/>wrap up &<br/>capture learnings"]
    C -.->|"weekly"| WI["/weekly-inventory<br/>tidy memory &<br/>promote principles"]
    WI -.-> N
VerbWhenWhat it does for you
/newsStart of a sessionBrings you up to speed on what changed since last time
(your work)—Claude creates the worktree, runs scoped tests, self-reviews with /review, opens the PR — merging stays your call
/close-chatEnd of a sessionWraps up, files the backlog, captures feedback into the learning loop
/weekly-inventoryWeeklyTidies memory and promotes repeated feedback into principles

That's the whole surface area. The other skills are called for you at the right moment — you never have to remember which one to run.


What actually gets better?

Before (vanilla Claude Code)

You   : "Fix the login bug"
Claude: → Edits directly on main
        → Reports "done" with no tests
        → Runs git push
You   : "...main is broken"

After (with sidekick)

You   : "Fix the login bug"
Claude: → Creates worktree (main untouched)
        → Confirms staging DB connection
        → Fixes → Runs scoped tests
        → /review (code + test + ops — 6 perspectives)
        → Creates PR (merging is your call)

On top of that, a learning loop compounds over time:

Session 1: "Use staging DB, not mocks" — you give feedback
Session 2: Same feedback (2nd occurrence detected)
Session 3: 3rd time → promoted to a principle in your brain
Session 4+: Claude proactively says "Running against staging DB"

In other words, you stop repeating yourself.


How is this different from other templates?

Vanilla Claude CodeTypical templatesidekick
Physically blocks dangerous ops❌△ (rules only)✅ hooks enforce
Reusable skills❌△✅ 17 skills
Learns your judgment❌❌✅ Thinking OS
Fully autonomous implementation❌❌✅ /auto-implement
Tracks design decisions (ADR)❌△✅

In short: other templates give you a ruleset (static docs). sidekick gives you a growing judgment system (dynamic).

Q. Claude Code only? Does it work with Cursor / Cline / Gemini? Yes, Claude Code only — hooks / skills / settings.json use Claude Code's format. That said, the core idea — teaching your judgment to an AI — is tool-agnostic.

Q. Solo dev or team? Both. No "enterprise edition." The same config scales with your team size (Worktree becomes essential for parallel work; /review becomes a team gate; PROTECTED_BRANCHES grows).

Q. API billing? Claude Max? Runs on the Claude Max subscription — no API charges. 10 projects for the same $100/month. (ADR-0003)

Q. Can I add it to an existing project? Yes. For projects in maintenance mode, start with just safety guards (hooks) and /review. The Thinking OS grows naturally over time.


Quick Start

How to get it

You are...PathCommand / Action
Starting a brand-new projectGitHub template (recommended)gh repo create my-project --template SideMountain/claude-code-sidekick --private --clone
Want a local copy to study or forkgit clonegit clone https://github.com/SideMountain/claude-code-sidekick.git
Adding to an existing projectManual overlaycp -r sidekick/CLAUDE.md sidekick/.claude/ your-project/, then run /setup
Already on sidekick, want a newer version/adopt-sidekick-updaterun /adopt-sidekick-update in the project

Then run /setup

After launching Claude Code, run /setup. It walks you through interactively (~5 minutes):

┌──────────────────────────────────────────────────┐
│ Step 1 : Project info                            │
│  Language / ORM / test command / staging toggle   │
│  → written to CLAUDE.md                          │
├──────────────────────────────────────────────────┤
│ Step 2 : Activate safety guards                  │
│  Block rm -rf, .env overwrites, push to main     │
│  → settings.json + hooks/                        │
├──────────────────────────────────────────────────┤
│ Step 3 : Deploy templates + brain                │
│  CLAUDE.local.md (personal config, gitignored)   │
│  Personal brain (~/.claude/brain/thinking.md)    │
├──────────────────────────────────────────────────┤
│ Step 4 : Your judgment principles (optional)     │
│  "Top priority? Speed / safety / user impact"    │
│  → grows naturally over time (fine to skip)      │
└──────────────────────────────────────────────────┘

Try it

"Fix the typo in README and create a PR"

Claude will automatically: create a worktree (main stays safe) → fix the typo → self-review with /review → open a PR for you to merge. That's your first taste.


🧠 Thinking OS — Claude learns your judgment

The core of sidekick. When session feedback repeats, it gets promoted to a principle that Claude follows automatically.

flowchart LR
    S["Session insight<br/>(correction/feedback)"] --> F["feedback_*.md<br/>recorded"]
    F --> P["/weekly-inventory<br/>pattern detection"]
    P -->|"3+ times<br/>detected"| C{"Promote?<br/>Your call"}
    C -->|"Yes"| T["personal brain<br/>becomes a principle"]
    C -->|"No"| F
    T --> A["Claude applies<br/>automatically"]
    A --> S

Promotion always requires your approval (not fully automatic). /weekly-inventory surfaces candidates; only what you approve enters your brain.

Where your judgment lives — the two-layer brain (ADR-0016)

sidekick splits judgment into two files so personal principles travel with you while project-specific rules stay local:

  • Personal brain — ~/.claude/brain/thinking.md: your decision axis, shared across every project (what you prioritize, what you never do, your failure patterns). You grow it; /adopt-sidekick-update never overwrites it.
  • PJ brain — <project>/.claude/brain/thinking.md: this project's judgment. It @imports your personal brain in one hop; if the personal brain is absent the import is silently ignored (fail-safe), so the project still loads.

The shipped brain/thinking.md at the repo root is a template only (not loaded) — /setup copies it to ~/.claude/brain/thinking.md only when you don't already have one, so an existing personal brain is never clobbered.

FileDefinesChanges when...
~/.claude/brain/thinking.mdYour decision principles — portable across all projects (personal brain)Your thinking changes
<project>/.claude/brain/thinking.mdThis project's judgment axis (PJ brain; @imports your personal brain)Project-specific judgment changes
rules/*.mdProject rules (coding standards, DB, Git strategy)The project changes
CLAUDE.mdProject config + HARD/SOFT/GUIDE rulesThe project changes

🛡️ Three-layer defense — safety is non-negotiable

flowchart LR
    OP["Claude's<br/>action"] --> L1
    L1["① Awareness<br/>CLAUDE.md<br/>HARD/SOFT/GUIDE"] --> L2
    L2["② Enforcement<br/>Pre-tool Hooks<br/>(physical block)"]
    L2 -->|"dangerous op"| DENY(("DENY"))
    L2 --> L3
    L3["③ Detection<br/>/review<br/>6 perspectives"] --> SAFE["Safe<br/>change"]
LayerMechanismExample
① AwarenessCLAUDE.md rules (HARD / SOFT / GUIDE)"Don't push to main"
② EnforcementPre-tool hooks (JSON deny = blocked)guard-bash.sh blocks rm -rf
③ Detection/review skill (6 perspectives)Catches security issues in PR

Four levels of blocking:

  1. Deny list (settings.json) — never runs: prisma db push, force push
  2. Guard blocks (hooks) — JSON deny: rm -rf, .env changes, protected branch push, prod DB ops
  3. HARD rules — Claude asks you first: git push (feature), gh pr create, gh pr merge
  4. Everything else — auto-approved via Bash(*) (no dialogs)

🧰 The 17 skills

The three verbs above (/news, /close-chat, /weekly-inventory) are the ones you run by hand. The rest are plumbing — called when the moment comes.

CategorySkillsPurpose
Ideation/discoverIdea → requirements (gap analysis, task breakdown)
Review/review, /review-code, /review-test, /review-ops, /review-design, /review-specRuns only relevant perspectives based on change scope
Lifecycle/setup, /close-chat, /weekly-inventory, /newsSession & project management
Health/tuneSpeed up tests/CI, prune-free test inventory (consolidate/strengthen), code dedup — read-only audit → human-gated
Knowledge/record-decision, /inventoryADR recording, version tracking
Updates & Release/adopt-sidekick-update, /releasePull upstream updates / cut a versioned release
Automation/auto-implementFull auto: implement → test → review → PR

🔄 How the skills connect

/discover and /auto-implement are the two ends of one pipeline. Everything between happens automatically.

flowchart LR
    Idea["💡 Idea"] --> D["/discover<br/>requirements<br/>& tasks"]
    D --> Design["📋 Design<br/>confirmed"]
    Design --> AI["/auto-implement<br/>Phase 0-5"]
    AI --> R["/review<br/>6 perspectives"]
    R --> PR["📤 PR"]
    PR --> CC["/close-chat<br/>learning loop"]
    CC -.->|"feedback"| TH["personal brain<br/>(principles)"]
    TH -.->|"applied next<br/>session"| Idea

🌙 Auto mode — PRs while you sleep

You   : "Design looks good. /auto-implement #10, #11, #12"
Claude: → Creates 3 worktrees in parallel
        → Implements each issue independently
        → Runs /review on each
        → Pushes and creates 3 PRs
You   : (morning) Review and merge PRs

Fully unattended (overnight, AFK):

SIDEKICK_AUTO=true claude --dangerouslySkipPermissions \
  -p "/auto-implement #10, #11, #12"
flowchart LR
    P0["Phase 0<br/>Design<br/>Check"] --> P1["Phase 1<br/>Worktree<br/>Setup"]
    P1 --> P2["Phase 2<br/>Implement<br/>Isolated"]
    P2 --> P3["Phase 3<br/>/review<br/>max 3 rounds"]
    P3 --> P4["Phase 4<br/>Test<br/>Push PR"]
    P4 --> P5["Phase 5<br/>Learning Loop<br/>Capture"]
    P0 -..->|"not ready"| STOP(("STOP"))
    P3 -..->|"BLOCKER"| STOP

Always manual, even in auto mode: PR merge to main / DB migrations / production deploys. Advanced setup (cron, Slack) → cron-setup-guide.md

🗂️ Architecture

your-project/
├── CLAUDE.md                    # Rules & config (HARD/SOFT/GUIDE)
├── brain/
│   └── thinking.md              # Personal-brain TEMPLATE (not loaded; /setup copies to ~/.claude/brain/)
├── .claude/
│   ├── hooks/                   # Safety enforcement layer (guard-bash, db-operation, session-start, …)
│   ├── skills/                  # 17 reusable workflows
│   ├── brain/
│   │   └── thinking.md          # PJ brain (@imports personal brain ~/.claude/brain/thinking.md)
│   ├── rules/                   # Project rules (coding standards, DB, Git strategy)
│   ├── templates/               # Opt-in files deployed by /setup
│   └── settings.json            # Permissions, hooks, deny list
└── docs/
    └── decisions/               # Architecture Decision Records

Configuration

Set in Project Configuration at the top of CLAUDE.md:

SettingDescriptionDefault
PROJECT_NAMEProject name""
STG_ENABLEDStaging environmentfalse
ORM_TYPEprisma / drizzle / nonenone
LANGUAGEtypescript / pythontypescript
NOTION_ENABLEDExternal task DB integrationfalse
TEST_COMMANDTest runner command""
BUILD_COMMANDBuild command""

Design Principles

  1. Knowledge compounds: Session insights flow from feedback → principles → Thinking OS. Your AI gets better every week. (ADR-0007)
  2. Safety is non-negotiable: Hard blocks are never overridden. Not by auto mode, not by user request, not by clever workarounds.
  3. Blacklist over whitelist: Only dangerous things are listed. Everything else runs automatically. (ADR-0002)
  4. Fixed cost, not per-project: Runs on Claude Max. No API charges. 10 projects for the same $100/month. (ADR-0003)
  5. Git is the source of truth: No external DB required. CLAUDE.md + ADR + GitHub Issues + auto-memory. Notion is optional. (ADR-0004)

📐 For the full design philosophy at a glance, see docs/design.md — a one-page digest of how sidekick is designed today.


Versioning & updates

sidekick uses git tags + GitHub Releases for version management. Each project tracks its adopted version in CLAUDE.md:

SIDEKICK_VERSION: "0.8.0"

Run /inventory to check for updates against the latest GitHub Release.

Release severity

Releases are classified into 3 levels (ADR-0009):

  • ⚠️ [CRITICAL]: Security / critical bug fix. Immediate adoption recommended.
  • (No prefix): Standard — normal feature/fix release (default).
  • 💡 [ENHANCEMENT]: Opt-in improvements. Safe to defer.

Severity is shown in the Release title and banner, and emitted as a machine-readable severity: marker in the body. /inventory reads the marker (falling back to the title) to signal urgency.

Receiving updates (/adopt-sidekick-update)

Pull new releases with /adopt-sidekick-update. It is interactive and category-batched: it diffs your project against the target release, groups changes (rules / skills / hooks / docs), and lets you accept per category or drill into individual files. Declined items are remembered so they aren't re-proposed.

Your personal brain (~/.claude/brain/thinking.md) is never auto-overwritten — template updates are offered as a diff you approve (ADR-0016).

Typical flow: /inventory (detects the gap + severity) → /adopt-sidekick-update (apply) → SIDEKICK_VERSION bumped.


Feedback

Using sidekick? Tell us what works, what doesn't, and what's missing. File a Downstream Feedback issue — it helps improve the template for everyone.

License

MIT

Ver o original no GitHub

Bom para

Relacionados