Brewcode Overview

Brewcode is a plugin for Claude Code that turns single sessions into an infinite task pipeline with automatic context handoff between sessions. The name is a nod to brewing: skills (recipes) define what to brew, agents (brewers) do the work, and hooks (processes) manage the lifecycle.

Key Features

infinity

Infinite context

Automatic knowledge transfer between sessions via KNOWLEDGE.jsonl and the handoff mechanism. Tasks continue after compaction without losing progress.

terminal

15 skills (recipes)

Full cycle: from project analysis (/brewcode:setup) to task execution (/brewcode:start) and code review (/brewcode:standards-review).

users

13 agents (brewers)

Specialized agents: developer, tester, reviewer, architect, skill-creator, agent-creator, and coordinators.

settings

8 hooks (processes)

Lifecycle hooks for context management: knowledge injection, grepai integration, exit blocking when a task is still active.

Semantic search

Integration with grepai — AI-powered code search via Ollama + bge-m3. Auto-start, reminders, configurator.

shield

Code quality

Standards-review, convention analysis, secrets-scan, text-optimize. Rules are automatically synced to .claude/rules/.

Architecture

Brewcode works as a layer on top of Claude Code through the hook system. The plugin has no external runtime — all context is managed through built-in Claude Code events.

                         Brewcode Plugin
  ┌──────────────────────────────────────────────────────────┐
  │                                                          │
  │   Skills (recipes)            Agents (brewers)           │
  │   ┌──────────────┐          ┌──────────────────┐         │
  │   │ setup, spec  │          │ developer, tester │         │
  │   │ plan, start  │ ──────>  │ reviewer, architect│         │
  │   │ convention,. │          │ coordinator, ...  │         │
  │   └──────────────┘          └──────────────────┘         │
  │          │                          │                     │
  │          v                          v                     │
  │   Hooks (processes)           Templates + Knowledge      │
  │   ┌──────────────┐          ┌──────────────────┐         │
  │   │ session-start│          │ PLAN.md.template  │         │
  │   │ pre-task     │ <──────> │ KNOWLEDGE.jsonl   │         │
  │   │ pre-compact  │          │ SPEC.md.template  │         │
  │   │ stop         │          │ artifacts/        │         │
  │   └──────────────┘          └──────────────────┘         │
  │                                                          │
  └──────────────────────────────────────────────────────────┘

Task execution flow

PLAN.md --> phases (phases/) --> agents execute --> hooks manage
   │                               │                     │
   │  Phase Registry               │  Task API           │  SessionStart
   │  (phase table)                │  (create/update)    │  PreToolUse
   │                               │                     │  PostToolUse
   v                               v                     │  PreCompact
artifacts/{P}-{N}{T}/          KNOWLEDGE.jsonl            │  Stop
{AGENT}_output.md              (knowledge accumulation)   v
                                                    handoff (auto)

Plugin structure

brewcode/
├── .claude-plugin/
│   └── plugin.json                    # Plugin manifest
├── hooks/
│   ├── hooks.json                     # Binding 8 hooks to events
│   ├── session-start.mjs              # Session initialization
│   ├── grepai-session.mjs             # Auto-start grepai watch
│   ├── pre-task.mjs                   # Knowledge injection into agents
│   ├── grepai-reminder.mjs            # grepai reminder
│   ├── post-task.mjs                  # Session binding, 2-step protocol
│   ├── pre-compact.mjs               # Knowledge compaction, handoff
│   ├── stop.mjs                       # Exit blocking
│   ├── forced-eval.mjs                # Skill activation (84%)
│   └── lib/
│       ├── utils.mjs                  # I/O, lock files, configuration
│       └── knowledge.mjs             # KNOWLEDGE.jsonl operations
├── agents/                            # 13 agents
│   ├── developer.md                   # Feature implementation (opus)
│   ├── tester.md                      # Testing (sonnet)
│   ├── reviewer.md                    # Code review (opus)
│   ├── architect.md                   # Architecture (opus)
│   ├── skill-creator.md               # Skill creation (opus)
│   ├── agent-creator.md               # Agent creation (opus)
│   ├── hook-creator.md                # Hook creation (opus)
│   ├── text-optimizer.md              # Text optimization (sonnet)
│   ├── bash-expert.md                 # Bash scripts (opus)
│   ├── bc-coordinator.md              # Task coordinator (haiku)
│   ├── bc-knowledge-manager.md        # Knowledge manager (haiku)
│   ├── bc-grepai-configurator.md      # grepai configurator (opus)
│   └── bc-rules-organizer.md          # Rules organizer (sonnet)
├── skills/                            # 15 skills
│   ├── setup/                         # Project analysis, templates
│   ├── spec/                          # Specification creation
│   ├── plan/                          # Plan creation
│   ├── start/                         # Task execution
│   ├── convention/                    # Convention analysis
│   ├── rules/                         # Rule extraction
│   ├── grepai/                        # Semantic search
│   ├── install/                       # Dependency installation
│   ├── teardown/                      # Cleanup
│   ├── text-optimize/                 # Text optimization
│   ├── text-human/                    # Code humanization
│   ├── standards-review/              # Standards review
│   ├── skills/                        # Skill management
│   ├── agents/                        # Agent management
│   └── secrets-scan/                  # Secrets scanning
└── templates/                         # Rule templates

Target project structure

After running /brewcode:setup and /brewcode:start, the following appears in your project:

{PROJECT}/
└── .claude/
    └── tasks/
        ├── cfg/
        │   ├── brewcode.config.json    # Plugin configuration
        │   └── brewcode.state.json     # Execution state
        ├── templates/                  # Adapted templates
        │   ├── PLAN.md.template
        │   ├── SPEC.md.template
        │   └── phase*.template
        ├── logs/
        │   └── brewcode.log            # Hook log
        ├── sessions/
        │   └── {session_id}.info       # Session information
        └── {TS}_{NAME}_task/           # Task directory
            ├── PLAN.md                 # Execution plan
            ├── SPEC.md                 # Specification
            ├── KNOWLEDGE.jsonl         # Accumulated knowledge
            ├── phases/                 # Phase files
            │   ├── 1-create-entity.md
            │   ├── 1V-verify-entity.md
            │   └── FR-final-review.md
            ├── artifacts/              # Agent reports
            │   ├── FINAL.md
            │   └── {P}-{N}{T}/
            ├── backup/                 # Backups
            └── .lock                   # Session lock file

Components in detail

Skills

15 skills (recipes) cover the full task lifecycle. See the Skills section for details.

Group	Skills	Purpose
Core cycle	setup, spec, plan, start	Task creation and execution
Quality	standards-review, convention, rules, secrets-scan	Code analysis and review
Utilities	grepai, install, teardown, text-optimize, text-human, skills, agents	Tools and configuration

Agents

13 agents (brewers) with different models and specializations. See the Agents section for details.

Role	Agents	Model
Implementation	developer, tester, architect	opus/sonnet
Review	reviewer	opus
Creation	skill-creator, agent-creator, hook-creator	opus
Optimization	text-optimizer, bash-expert	sonnet/opus
Coordination	bc-coordinator, bc-knowledge-manager, bc-grepai-configurator, bc-rules-organizer	haiku/sonnet/opus

Hooks

8 hooks (processes) manage the lifecycle through Claude Code events. See the Hooks section for details.

Event	Hooks	Purpose
UserPromptSubmit	forced-eval	Skill activation
SessionStart	session-start, grepai-session	Initialization
PreToolUse	pre-task, grepai-reminder	Context injection
PostToolUse	post-task	Session binding
PreCompact	pre-compact	Knowledge handoff
Stop	stop	Exit blocking

Recommended launch order

Installation/brewcode:install
Install dependencies: brew, coreutils, jq, optionally grepai.
Project setup/brewcode:setup
Analyze the project and generate adapted templates.
Specification/brewcode:spec
Parallel codebase research, SPEC.md creation.
Plan/brewcode:plan
Phase generation, quorum review, requirements tracing.
Execution/brewcode:start
Launch the task with infinite context and automatic handoff.

Next steps

Check out Skills for a detailed description of all 15 skills, or go to Workflow for a deep dive into the full task execution cycle.