Skip to content

ediestel/fred-contract-coding

BranchesTags

Repository files navigation

Fred - Contract Coding

CAVE: this codebase is a basic concept, status: when I started this idea. Meanwhile 'intelligent Fred' is at almost full capacity. Use Claude code to make contract coding work for you. I just set up local cooperation with https://github.com/thedotmack/claude-mem (04/02/2026); also I have another concept developing https://github.com/ediestel/fred_helps_claude_code

Me-in-the-Loop governance for AI coding agents.

Fred adds a contract-based approval layer between you and autonomous AI coding tools. Instead of letting AI make unlimited changes, every significant action requires explicit approval through structured contracts.

Version 3.0 | 19 Workflows | Kanban Board | Pipeline Builder | Desktop App | File Labels

Why Fred?

AI coding agents are powerful but can make mistakes - especially on complex, multi-file changes. Fred provides:

  • Contract Boundaries: Max 3 files per approval cycle by default
  • Interpretation Verification: See how the AI understood your request before work begins
  • Risk Assessment: Automatic analysis of task complexity and recommended workflow
  • Audit Trail: Full history through Temporal.io durable workflows
  • Graduated Autonomy: Simple tasks skip contracts, complex ones require approval

The Core Insight

"AI code changes should be contracts, not commands."

Problem Traditional AI Fred's Approach
AI misunderstands Hope it doesn't interpretation field catches it early
Risky changes YOLO risks field + human approval gate
Large changes One massive diff Walker: max 3 files per step
High-stakes code Same model for everything Surgeon: Opus 4.5 for critical ops
Failures Start over Temporal: durable state, retries, rollback

Architecture

┌─────────────────────────────────────────────────────────────┐
│                       Fred Dashboard                        │
│                    (React + Next.js @ :4001)                │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      Fred Backend                           │
│                    (FastAPI @ :4000)                        │
│  ┌─────────────┐  ┌──────────────┐  ┌──────────────────┐    │
│  │ API Proxy   │  │ Contract     │  │ Workflow         │    │
│  │ Gate        │  │ Advisor      │  │ Management       │    │
│  └─────────────┘  └──────────────┘  └──────────────────┘    │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                     Temporal.io Server                      │
│                        (@ :7233)                            │
│   Durable workflow execution, state management, history     │
└─────────────────────────────────────────────────────────────┘

Quick Start

Prerequisites

One-Command Startup

# Clone and enter
git clone https://github.com/ediestel/fred.git
cd fred

# Install dependencies
pnpm install && pnpm install:all
pip install -r backend/requirements.txt

# Start everything
./start.sh

Start with Your Project

# Point Fred at your project
FRED_REPO_ROOT=/path/to/your/project ./start.sh

# With MCP git context enrichment
FRED_REPO_ROOT=/path/to/project FRED_MCP_ENABLED=true ./start.sh

# With n8n workflow automation
FRED_N8N_ENABLED=true ./start.sh

Changing Target Repository

You can change the repo via UI (Config tab) or API:

curl -X POST http://localhost:4000/api/repo-root \
  -H "Content-Type: application/json" \
  -d '{"repo_root": "/path/to/other/project"}'

Restart required?

  • Workflows: No - new repo used immediately
  • MCP git context: Yes - restart to pick up new repo

Access Points

Service URL Description
Dashboard http://localhost:4001 React frontend
API http://localhost:4000 FastAPI backend
Temporal UI http://localhost:8233 Workflow monitoring
MCP Bridge http://localhost:3100 Git context (if enabled)
n8n http://localhost:5678 Automation (if enabled)

Features

Kanban Board

Visual workflow management at /kanban:

Feature Description
Diff preview Click 👁️ on awaiting cards to see proposed changes
Accept/Reject One-click with optional feedback
Save as Preference After reject, save feedback as persistent rule
Undo accept 30-second window to rollback after accept
Quick-start "+" button in Backlog for common intents
Drag-and-drop Move cards between columns

MCP Integration

Fred supports Model Context Protocol for enriching contracts:

  • Git context: Automatic diff, status, branch, commits
  • User preferences: Persistent code style settings
  • Prompt templates: Custom rules per workflow type
# Create a preference
curl -X POST http://localhost:4000/api/preferences \
  -H "Content-Type: application/json" \
  -d '{"key":"code_style","value":"prefer async/await","category":"code_style"}'

File Labels

Fred includes a structural labeling system that classifies source files for intelligent workflow selection:

Label Format Description
ROLE CTRL, DATA, UTIL, VIEW, SERVICE File's architectural purpose
EFFECT PURE, IO Whether file has side effects
STABILITY STB, VOL Change frequency indicator

Risk-based workflow selection:

Pattern Risk Recommended Workflow
*.IO.STB High CodeSurgeon
CTRL.*.* Medium-High CodeWalker + review
UTIL.PURE.* Low CodeWalker

Enable labels per repository:

mkdir -p .fred && echo "true" > .fred/labels_enabled

Query labels via API:

curl "http://localhost:4000/api/labels?repo_root=/path/to/project"

Contract System

Every significant task goes through:

  1. Analysis - AI estimates scope, risk, recommends workflow
  2. Interpretation - AI states how it understood your request
  3. Proposal - Specific changes with reasoning
  4. Review - You approve, reject, or provide feedback
  5. Execution - Approved changes are applied
  6. Iteration - Loop until complete or max iterations

Workflows (19 Total)

Code Modification

Workflow Use Case Risk Level
CodeWalker Incremental changes with feedback Low-Medium
CodeSurgeon Critical changes, multi-signoff High
CodeModify General code modifications Medium
Cleanup Dead code removal Low-Medium
FeatureImpl New feature implementation Medium

Analysis (Read-Only)

Workflow Use Case Risk Level
CodeReview Code analysis, no changes Low
SecurityScan Vulnerability scanning Medium
DebugSession Bug investigation Medium
RefactorAnalysis Code smell detection Medium

Documentation

Workflow Use Case Risk Level
Explain Code explanations Low
Document Generate documentation Low
Architecture Architecture recommendations Low

Special

Workflow Use Case Risk Level
GenerateTests Generate test cases Low
Migrate Version/framework upgrades High
IsolateBranch Experimental work in isolation Medium

Orchestration & Interactive

Workflow Use Case Risk Level
Pipeline Multi-workflow sequences Medium
TalksWithAgent Conversational AI coding Medium
CodeChangeApprovalPipeline AI-proposed changes with human gates Medium
LabelRefresh Update file labels for codebase Low

Project Structure

fred/
├── backend/
│   ├── temporal/
│   │   ├── api/              # FastAPI server + preferences API
│   │   ├── workflows/        # Temporal workflow definitions
│   │   ├── activities/       # Workflow activities + MCP client
│   │   ├── models/           # Contract models (Pydantic)
│   │   ├── interceptors/     # Fred enforcement layer
│   │   ├── prompts/          # Prompt templates
│   │   └── FRED_MANUAL.md    # Workflow documentation
│   ├── mcp-config.json       # MCP bridge configuration
│   └── requirements.txt
├── frontend/
│   ├── app/                  # Next.js pages
│   │   └── kanban/           # Kanban board view
│   ├── components/           # React components
│   └── lib/                  # API client, utilities
├── start.sh                  # One-click startup
└── README.md                 # This file

Environment Variables

Variable Description Default
ANTHROPIC_API_KEY Anthropic API key Required
FRED_API_KEY Fred server authentication Optional
FRED_REPO_ROOT Target project path Current dir
FRED_MCP_ENABLED Enable MCP integration false
FRED_N8N_ENABLED Enable n8n automation false

API Endpoints

Endpoint Method Description
/api/workflows GET List all workflows
/api/start POST Start new workflow
/api/workflow/{id}/poll GET Poll for approval
/api/workflow/{id}/approve-inline POST Approve/reject
/api/preferences GET/POST/DELETE User preferences
/api/templates GET/POST/PUT/DELETE Prompt templates
/api/kanban/state POST Get Kanban board
/api/labels GET Get file labels
/api/pipeline/start POST Start code change pipeline
/api/pipeline/{id}/approve POST Approve pipeline change
/api/pipeline/{id}/escalate POST Escalate for review
/api/pipeline/{id}/status GET Get pipeline status

Documentation

Document Description
backend/temporal/FRED_MANUAL.md Workflow selection guide, configuration, best practices
backend/temporal/FRED_COMPLETE_MANUAL.md Full reference: all 15 workflows, API, signals, queries

Philosophy

Fred embodies graduated autonomy:

  • Simple tasks (typo fixes) → Direct execution
  • Moderate tasks (multi-file refactors) → Contract with approval
  • Complex tasks (architecture changes) → Multiple approvals, strict limits

The goal isn't to slow down AI - it's to catch the 10% of cases where autonomous action would cause problems, while letting the 90% flow smoothly.

License

MIT License

Fred: Because autonomous AI needs accountable oversight.

About

Me-in-the-loop contract-based governance for AI coding agents

Resources

Readme

License

MIT license
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages