convez.ai
Agente
slabgorb

pennyfarthing

slabgorb/pennyfarthing

Ver no GitHub
InicialPluginScore · de 0 a 100

Pennyfarthing — Claude Code agent orchestration framework

Instalação

$npx convez-ai slabgorb/pennyfarthing

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
1
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 3 meses
Versão
v13.6.0
Issues abertas
17
Contribuidores
6

README

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

Pennyfarthing

v13.1.2 | The outer loop goes once, the inner loop goes many times.

A Claude Code agent orchestration framework built around three pillars: a flexible development platform, scientific personality research, and streamlined integrations.


What is Pennyfarthing?

1. Development Platform

A multi-agent system with customizable BikeLane workflows for structured software development:

  • 11 Coordinated Agents - SM, TEA, Dev, Reviewer, Architect, PM, Tech Writer, UX Designer, DevOps, Orchestrator, BA
  • 11 BikeLane Workflows - TDD, BDD, Trivial, 2-Party TDD, TDD-Team, BDD-Team, Patch, Agent-Docs, Architecture, Release, Git Cleanup
  • 38 Slash Commands - Entry points for agent activation and workflows
  • 25 Skills - Reusable knowledge domains (testing, code-review, jira, settings, mermaid, etc.)
  • Prime Context System - Tiered context injection assembles agent definition, persona, session state, and sidecar memory
  • Automatic Handoffs - Context-aware agent transitions via subagent delegation
  • Agent Sidecars - Persistent learning files where agents record patterns, gotchas, and decisions across stories
  • Frame TUI - Textual-based terminal dashboard running alongside Claude Code CLI

2. Personality Research

A scientific study of how strong personalities affect AI agent behavior:

  • OCEAN Profiling - Big Five personality scores for every character
  • TRAIL Framework - Categorizing errors (reasoning, planning, execution) and correlating with personality
  • Benchmarking System - /solo, /benchmark-control, /benchmark for statistical evaluation
  • JobFair - Discovering which characters excel at roles beyond their native specialization

The 45 persona themes (Discworld, Star Trek, Breaking Bad, Alice in Wonderland, etc.) are instruments of inquiry, not decoration. Early findings show character expertise often trumps abstract personality scores.

3. Integration & Tooling

  • Frame - Dashboard panel viewer for CLI-first developers — terminal TUI alongside Claude Code
  • Jira Integration - Bidirectional sync, epic auto-creation, sprint velocity
  • Sprint Management - Story tracking with current-sprint.yaml
  • Codebase Analysis - Hotspots, complexity, dead code, dependencies, code markers, and health score via pf debug

Quick Start

Three paths depending on who you are:

Path A: Join a project that already uses Pennyfarthing

Someone on your team already ran /pf-setup. You just need the CLI and to clone.

# 1. Install the CLI (pick one)
pipx install "git+https://github.com/slabgorb/pennyfarthing.git"
# or: uv tool install "pennyfarthing-scripts @ git+https://github.com/slabgorb/pennyfarthing.git"

# 2. Clone the project
git clone git@github.com:your-org/your-project.git && cd your-project

# 3. Start Claude Code — bootstrap runs automatically on first session
claude

That's it. The project's committed bootstrap.sh hook detects the first session, runs pf init, and sets everything up. You'll see agents, themes, and workflows immediately.

If pf isn't installed when you start Claude Code, the bootstrap will attempt to install it via uv, pipx, or pip automatically.

Path B: Add Pennyfarthing to your own project

You're bringing Pennyfarthing into a repo for the first time.

# 1. Authenticate with GitHub (required — private repo)
gh auth login

# 2. Install the CLI (pick one)
pipx install "git+https://github.com/slabgorb/pennyfarthing.git"
# or: uv tool install "pennyfarthing-scripts @ git+https://github.com/slabgorb/pennyfarthing.git"
# or: curl -fsSL https://raw.githubusercontent.com/slabgorb/pennyfarthing/main/pennyfarthing-dist/scripts/install.sh | bash

# 3. Initialize your project
cd your-project
pf init

# 4. Verify
pf doctor

# 5. Start Claude Code and run interactive setup
claude
/pf-setup    # walks through repo discovery, CLAUDE.md, theme selection, Jira, etc.

# 6. Start working
/pf-work

pf init creates the .pennyfarthing/ and .claude/ directories. /pf-setup configures them interactively — repo topology, project context, theme, and optional integrations. After setup, teammates can follow Path A.

Path C: Develop Pennyfarthing itself (dogfooding)

You're contributing to the framework using the orchestrator repo.

# 1. Clone the orchestrator (includes pennyfarthing/ as inlined subrepo)
git clone git@github.com:slabgorb/orc-penny.git && cd orc-penny

# 2. Setup — clones pennyfarthing/, installs deps, builds, installs pf CLI
just setup

# 3. Launch Claude Code with OTEL telemetry
just claude

# 4. Optional: interactive walkthrough
/guided-tour

Prerequisites: Python 3.11+, Node 18+, pnpm 9+, just, Claude Code CLI, Git SSH access to slabgorb.

The orchestrator has two git repos — orc-penny/ (sprint files, sessions, docs, trunk-based on main) and pennyfarthing/ (framework source, gitflow on develop). The .pennyfarthing/ runtime directory symlinks to pennyfarthing/pennyfarthing-dist/ so changes are live immediately.

Full walkthrough: See Getting Started for detailed installation, setup, and first work session guide.

Display Modes

Pennyfarthing works in any terminal. Optional dashboards add real-time visibility into agent activity.

I want to...ModeCommand
Just use agents in my terminalCLI onlyclaude (no dashboard needed)
Stay fully in the terminalFrame TUIjust tui + just claude
One command, everythingFrame all-in-onepf frame start

See the full Frame Guide for setup, panels, and OTEL telemetry.

Visual Dashboards

Frame provides 15 dashboard panels showing real-time agent activity:

Panels

All panels are draggable, floatable, and splittable:

PanelPurpose
SprintCurrent sprint stories and progress
ProgressAt-a-glance story dashboard
BikeLaneWorkflow phase state and navigation
ACAcceptance criteria checklist with progress
ChangedFiles modified during the session
DiffsGit diff viewer for current changes
GitBranch management and status
TodoTask list tracking
Audit LogTimestamped tool use history
WorkflowWorkflow navigation and status
HotspotsCodebase health — dead code, complexity
SettingsPermission mode, relay mode, bell mode
DebugPrime context inspection with token counts
BackgroundBackground job monitoring

Architecture

Frame is powered by Frame, a Python FastAPI/uvicorn server that serves API endpoints, WebSocket channels, and the OTLP telemetry receiver:

graph TB
    subgraph "Frame"
        BR["Python FastAPI server"]
    end

    BR --> WH["Frame<br/>(uvicorn)"]

    BR -- "writes" --> BP[".frame-port"]

    WH --> API["/api/* endpoints"]
    WH --> WS["/ws/* channels"]
    WH --> OTLP["/v1/* OTLP receiver"]

Tool Visualization

Frame renders tool use as human-readable summaries instead of raw JSON. Consecutive identical tool calls are stacked, and results are collapsible.

Agent Portraits

Each persona character has a unique portrait displayed in the conversation stream, making multi-agent workflows visually distinct.

Workflow Modes

ModeDescription
Permission Modeplan / manual / accept — controls how much Claude can do without approval
Relay ModeAutomatic agent handoffs — detects CYCLIST:HANDOFF markers and runs the next agent
Bell ModeQueue messages while Claude works — injected at next tool execution via hooks

Prime Context System

Prime assembles the full agent context at activation: agent definition, persona character, behavior guide, sprint state, active session, and sidecar memory. This is injected via --append-system-prompt so agents behave identically regardless of display mode.

Prime uses tiered injection to manage token overhead:

TierTokensWhen
Full~4000New session or new agent
Refresh~600Same agent, stale context
Handoff~700Agent-to-agent transition
Minimal~200Deep in same agent session

Agent Sidecars

Sidecars are persistent learning files where agents record what they discover during story work. Each agent maintains three files in .pennyfarthing/sidecars/:

  • {agent}-patterns.md — Strategies and patterns that worked
  • {agent}-gotchas.md — Mistakes and edge cases to avoid
  • {agent}-decisions.md — Architecture decisions and rationale

Agents write to sidecars before every handoff. Prime loads them on activation, so agents build on previous experience instead of rediscovering the same issues.

BikeLane Workflows

BikeLane is the umbrella workflow system supporting two types:

TypeDescriptionExamples
PhasedAgent-driven with automatic handoffstdd, bdd, trivial, agent-docs
SteppedProgressive disclosure with user gatesarchitecture, release, git-cleanup

Example: TDD Workflow (Phased)

AgentRolePhase
SMScrum MasterStory selection, session setup, completion
TEATest EngineerWrite failing tests (RED)
DevDeveloperMake tests pass (GREEN)
ReviewerCode ReviewerQuality validation, approve/reject

Use /workflow list to see all workflows. Use /workflow start <name> to begin any stepped workflow.

Workflow Gates

Gates are conditional checks on phase transitions. When an agent finishes a phase, the gate evaluates whether the transition should proceed:

GatePurpose
tests-passVerify all tests pass before review
tests-failVerify tests are RED before implementation
approvalVerify reviewer has approved
confidence-smCheck if user instruction is unambiguous

Gates are defined in pennyfarthing-dist/gates/ and referenced via gate.file in workflow YAML.

Tandem Mode

Tandem workflows pair a background observer with the primary agent. The backseat watches the primary agent's work and injects observations:

  • TDD-Tandem — Architect watches TEA, TEA watches Dev, PM watches Reviewer
  • BDD-Tandem — Adds UX Designer watching Dev, Architect watching UX

For active questions (not passive observation), agents use the Consultation Protocol — synchronous Sonnet-powered request/response between agents.

Benchmarking & Personality Research

Pennyfarthing includes a scientific benchmarking system for evaluating how personality affects agent performance:

# Run a single agent on a scenario
/solo theme:agent --scenario cache-invalidation

# Create a control baseline (10 runs)
/benchmark-control reviewer --scenario order-service

# Compare persona vs control with statistics
/benchmark breaking-bad reviewer --scenario order-service

Key Findings:

  • Cohen's d effect sizes measure performance differences
  • Multivariate OCEAN patterns predict better than individual traits
  • Character expertise often trumps abstract personality scores
  • The "Stoic Analyst" profile (Low O + High C + Low E + Low N) excels at code review

See Benchmarking Documentation for methodology.

CLI Commands

CommandDescription
pf initInitialize Pennyfarthing in a project
pf doctorCheck installation health
pf doctor --fixAuto-fix common issues
pf validateRun all validators
pf theme listShow available themes
pf theme set <name>Change active theme
pf package listShow installable theme plugins
pf frame startLaunch Frame dashboard
pf sprint statusCurrent sprint overview
pf workflow listShow all workflows
pf debug hotspots analyzeGit change frequency analysis
pf debug deadcode staleFind files with no recent commits
pf debug healthscore analyzeComposite codebase health score
pf handoff marker <agent>Generate handoff marker

Documentation

Guides (in pennyfarthing-dist/guides/)

GuideDescription
BikeLaneWorkflow engine — phased, stepped, procedural
FrameStandalone panel viewer for CLI-first development
GatesWorkflow phase transition gates
Handoff CLIPhase transitions and marker generation
HooksHook system configuration and reference
PrimeAgent activation and context loading
Bell ModeMessage queue injection
Relay ModeAutomatic agent handoffs
ReflectorAgent-to-UI marker protocol
TirePumpContext clearing system
Tandem ProtocolBackground observer pairing
Output StylesConfigurable response modes
Brownfield ToolsCodebase analysis CLI tools
Peloton TestingPipeline replay benchmarks from real PR reviews
BenchmarksPersona evaluation system (JobFair)

Available Themes (45)

All 45 themes are bundled with pf init — no separate packages required. Themes span sci-fi, prestige TV, literature, mythology, comedy, history, and more:

the-expanse, star-trek-tng, breaking-bad, discworld, fifth-element, succession, the-wire, mad-men, shakespeare, jane-austen, dune, game-of-thrones, the-office, monty-python, greek-mythology, blade-runner, doctor-who, harry-potter, foundation, ted-lasso, alice-in-wonderland, firefly, and more.

All themes include OCEAN (Big Five) personality profiles. See Personas for personality analysis.

Setting a Theme

pf theme set the-expanse

Or configure directly in .pennyfarthing/config.local.yaml:

theme: the-expanse

Directory Structure

After initialization:

your-project/
├── .pennyfarthing/
│   ├── agents/               # Agent behavior definitions
│   ├── guides/               # Component documentation
│   ├── gates/                # Workflow transition gates
│   ├── output-styles/        # Response format definitions
│   ├── personas/             # Character and theme files
│   ├── scripts/              # Runtime scripts
│   ├── templates/            # Project templates
│   ├── workflows/            # BikeLane workflow definitions
│   ├── sidecars/             # Agent learning files (local, writable)
│   ├── config.local.yaml     # Theme, output style, modes
│   └── repos.yaml            # Multi-repo topology
├── .claude/
│   ├── commands/             # Slash commands for Claude Code discovery
│   └── skills/               # Skills for Claude Code discovery
├── sprint/
│   ├── current-sprint.yaml   # Active sprint
│   └── archive/              # Completed sessions
└── .session/
    └── {story-id}-session.md # Active work session

What's New in v13.0.0

  • Python-first architecture (ADR-0034) — Python owns the runtime: CLI, Frame server (FastAPI/uvicorn), hooks, benchmarks. TypeScript/React is GUI-only
  • Frame TUI — Textual-based terminal dashboard running alongside Claude Code CLI via pf frame start
  • Frame rewrite — Python FastAPI server replaces Node.js, serving API endpoints, WebSocket channels, and OTLP telemetry
  • Spec-check and spec-reconcile phases — Architect validates implementation alignment before review, reconciles deviations after
  • RepoFieldSpec registry — Typed metadata for repos.yaml fields, enabling TUI editing of project topology
  • Saddle mode — Background observer agent summon via pf saddle summon
  • Demo pipeline — pf demo generate builds presentation artifacts from sprint work
  • Pipeline replay benchmarks — Full TDD pipeline testing against real PR review findings via pf benchmark replay
  • OTEL telemetry — Traces, logs, and spans via Frame WebSocket channels

Previous Highlights

  • v12.7 - Judge versioning, pipeline replay framework, theme YAML schema, kitchen-sink workflow
  • v12.6 - Consumer E2E test suite, gold standard calibration, difficulty profiles
  • v12.0 - Python-first installation, monorepo consolidation, workflow gates, handoff CLI, output styles
  • v10.x - Frame Dockview, repos topology, tandem protocol, codebase health dashboard
  • v9.x - Theme expansion, release workflow, shadcn/ui migration, prime context, bell/relay modes
  • v8.x - BikeLane workflows, scientific benchmarking, JobFair, agent sidecars

See CHANGELOG.md for full details.


License

Copyright 2025-2026 Keith Avery. Licensed under Apache-2.0.

Ver o original no GitHub

Bom para

Relacionados