codehere

A governed, measurable AI coding OS that plans, edits, validates, and measures its own reliability. Every change is traceable, reviewable, and scored – so you can trust it on real code.

Codehere is a multi-agent coding system designed for solo developers and small teams. Unlike simple AI assistants, Codehere orchestrates specialized agents (Planning, Execution, Validation) to handle complex tasks while maintaining full transparency and control through review gates and trust metrics.

📖 Documentation → | 🗺️ Roadmap →

🚀 Installation

Global Installation (Recommended)

Option 1: Install from Local Directory

# Navigate to the agent directory
cd codehere/agent

# Install globally
npm install -g .

# Verify installation
codehere --version

Option 2: Install from npm (after publishing)

npm install -g codehere

Once installed globally, you can use codehere from any directory in your terminal.

Quick Start

First Time Setup:

# 1. Run the interactive setup wizard
codehere setup

# This will:
#   - Detect your API key (or guide you to configure it)
#   - Detect your codebase
#   - Configure model preferences
#   - Set up your environment

# 2. Index your codebase
codehere index

# 3. Start using Codehere!
codehere "How does authentication work?"

Switching Providers

Codehere supports multiple AI providers. By default, it uses Cohere (no configuration needed).

Quick Options:

Default (Cohere):

export COHERE_API_KEY=your-key
codehere status

OpenAI:

export CODEHERE_AI_PROVIDER=openai
export CODEHERE_OPENAI_API_KEY=sk-...
codehere status

Local LLM (Ollama, LM Studio):

export CODEHERE_AI_PROVIDER=local
export CODEHERE_LOCAL_BASE_URL=http://localhost:11434
codehere status

Fake Mode (Testing/Demo):

export CODEHERE_FAKE_AI=1
codehere status  # No API calls, deterministic outputs

Per-Operation Routing:

Create .codehere/providers.json to route different operations to different providers. See docs/PROVIDERS_QUICKSTART.md for complete setup guide.

📖 Complete Provider Guide →

Using Codehere:

# Natural language queries (unified command)
codehere "explain this function"
codehere "add error handling to src/utils.ts" --review
codehere "refactor user service to use dependency injection" --review

# Or use explicit commands
codehere ask "How does authentication work?"
codehere explain src/utils.ts
codehere plan "implement user authentication system"
codehere orchestrate "add comprehensive logging" --review

# Validation Mode: Review before applying changes
codehere fix src/utils.ts "Add error handling" --review
codehere orchestrate "Add authentication" --review
codehere plan "Refactor to DI" --execute --review

# Manage configuration
codehere config                    # Show current configuration
codehere config set autoCommit true
codehere config get defaultModel

# Get help
codehere --help
codehere help <command>

💡 Tip: Use --review on destructive operations (edit, orchestrate, plan --execute) to see summaries and approve changes before they're applied. This builds trust and prevents mistakes.

🔍 Validation Mode & Trust Scores

Validation Mode makes every agent operation traceable, reviewable, and measurable. Use --review to pause before applying changes, review structured summaries, and approve or reject. Every operation generates feedback that feeds into trust scores.

How it works:

• Run commands with --review to enable feedback capture
• Review summaries show files changed, validation checks, and risk assessment
• Feedback is stored locally in data/feedback/agent-feedback.jsonl
• Trust scores are computed per agent: (approved_success_runs / total_runs) × 100

Example:

# Enable review & feedback capture
CODEHERE_AUTO_APPROVE=true codehere fix src/file.ts "add input validation" --review

# View trust scores
npm run analyze:feedback
codehere status

Optional: Configure minimum trust thresholds via config/trust-config.json to highlight agents that need more validation (warnings only, non-blocking).

For CI/dashboards: Export trust and feedback stats as JSON:

• npm run analyze:feedback -- --json
• codehere status --json

For CI gates: Enforce minimum trust scores:

• npm run check:trust - Fails if any agent is below its configured threshold

📖 Complete Guide →

💬 Feedback Collection

Codehere collects feedback after operations to improve responses. In interactive mode, you'll see a prompt asking for feedback. In non-interactive mode (scripts, CI), you can provide feedback via environment variables:

# Positive feedback (thumbs up)
CODEHERE_FEEDBACK=y codehere ask "What is main?"

# Negative feedback (thumbs down)
CODEHERE_FEEDBACK=n codehere ask "What is main?"

# Request refinement with message
CODEHERE_FEEDBACK=r CODEHERE_FEEDBACK_MESSAGE="Add more examples" codehere ask "What is main?"

# Alternative values
CODEHERE_FEEDBACK=positive codehere ask "What is main?"
CODEHERE_FEEDBACK=negative codehere ask "What is main?"
CODEHERE_FEEDBACK=yes codehere ask "What is main?"
CODEHERE_FEEDBACK=no codehere ask "What is main?"

Environment Variables:

• CODEHERE_FEEDBACK: y/yes/positive (thumbs up), n/no/negative (thumbs down), r/refine/refinement (request refinement)
• CODEHERE_FEEDBACK_MESSAGE: Optional message for refinement requests

✨ Features

🎯 Why Codehere vs Other Coding Agents?

• Explicit Review Gates: Unlike agents that apply changes immediately, Codehere uses --review to pause, show summaries, and request approval before modifying files
• Trust Scores & Analytics: Every agent run is scored. Run npm run analyze:feedback to see which agents are most reliable in your workflow
• Full Traceability: Every operation generates a structured TraceSummary showing files changed, reasoning steps, validation checks, and risk assessment
• Governed Multi-Agent System: Specialized agents (Planning, Execution, Validation) work together with full instrumentation – not a black box
• Privacy-First Feedback: All feedback stored locally in JSONL. No telemetry. Opt-out available. Your data stays yours

🤖 Multi-Agent Orchestration

• Planning Agent: Breaks complex tasks into hierarchical sub-plans with risk assessment
• Execution Agent: Executes plans step-by-step, tracks file changes, handles rollbacks
• Validation Agent: Runs compilation checks, tests, and quality analysis before completion
• Intelligent Router: Automatically selects the right workflow (simple, ReAct, or multi-agent) based on query complexity
• Multi-Agent Orchestrator: Coordinates all agents, aggregates summaries, provides unified traceability

🛡️ Validation Mode & Review Gates

• --review Flag: Pause before applying changes, review structured summaries, approve or reject
• TraceSummary Generation: Every agent run produces a detailed summary (files, steps, checks, metrics, risk)
• Composite Summaries: Multi-agent operations merge all agent summaries into one reviewable report
• Risk Assessment: Automatic risk level calculation (low/medium/high/critical) with clear reasons
• Environment Controls: CODEHERE_AUTO_APPROVE=true for CI/CD, CODEHERE_FEEDBACK_OPT_OUT=true for privacy

📊 Trust & Reliability Metrics

• Agent Feedback Analytics: Run npm run analyze:feedback to see trust scores, success rates, and operation breakdowns
• Trust Score Calculation: (approved_success_runs / total_runs) × 100 – measurable agent reliability
• Outcome Tracking: Success, failure, partial_success, cancelled, error – complete visibility
• User Action Tracking: Approved, rejected, modified – understand how users interact with agents

🧠 Semantic Code Search & Context

• Builds local embedding index using Cohere's embedding API
• Enhanced context with file relationships and dependencies (15+ chunks)
• Context-aware responses using retrieved code
• Natural language code explanations and intelligent editing

🔒 Security & Privacy

• Local-first: All embeddings and feedback stored locally in SQLite
• No code transmission: Only chunks sent to API for embedding, never full files
• Audit trail: Complete JSONL logging of all operations
• Policy enforcement: Line limits, restricted folders, single-file safety checks
• Privacy controls: Opt-out available, anonymization by default

🔧 Enterprise Reliability

• Automatic error recovery: Retry with exponential backoff
• Circuit breaker: Protects against API failures
• Health monitoring: System health checks and metrics
• 24/7 operation ready: Robust error handling and graceful degradation

🏗️ Architecture

Multi-Agent System

┌─────────────────────────────────────────────────┐
│              Intelligent Router                  │
│  (Routes queries to appropriate workflow)        │
└───────────────┬─────────────────────────────────┘
                │
    ┌───────────┼───────────┐
    │           │           │
┌───▼───┐  ┌───▼────┐  ┌───▼──────────────┐
│ Simple│  │ ReAct  │  │ Multi-Agent      │
│ Work  │  │ Agent  │  │ Orchestrator     │
└───────┘  └────────┘  └──────┬───────────┘
                               │
                    ┌──────────┼──────────┐
                    │          │          │
            ┌───────▼──┐  ┌───▼──────┐  ┌▼────────────┐
            │ Planning │  │Execution │  │ Validation  │
            │  Agent   │→ │  Agent   │→ │   Agent     │
            └──────────┘  └──────────┘  └─────────────┘
                    │          │          │
                    └──────────┼──────────┘
                               │
                    ┌──────────▼──────────┐
                    │ Composite Summary   │
                    │ + Review Gate       │
                    │ + AgentFeedback     │
                    └─────────────────────┘

Core Components

• Intelligent Router: Analyzes query intent, selects optimal workflow
• Planning Agent: Creates hierarchical plans with risk assessment
• Execution Agent: Executes plans, tracks changes, handles rollbacks
• Validation Agent: Compiles, tests, analyzes quality
• Multi-Agent Orchestrator: Coordinates all agents, creates unified run context
• Validation Layer: TraceSummary generation, AgentFeedback recording, review handler

Data Flow

1. Query → Router determines intent
2. Planning → Agent creates plan with complexity tracking
3. Execution → Agent executes with file change tracking
4. Validation → Agent runs checks with pass/fail tracking
5. Summary → Composite summary aggregated from all agents
6. Review → User reviews summary, approves/rejects
7. Feedback → Outcome recorded to local JSONL, trust scores updated

Tech Stack:

• TypeScript - Type-safe development
• Cohere AI - Embeddings, chat completion, reranking
• SQLite - Local vector storage and feedback persistence
• Commander.js - CLI interface
• Clean Architecture - Domain, application, infrastructure layers

📊 Performance

• Indexing: ~2 seconds per chunk (rate-limited by API)
• Retrieval: <100ms for 200+ chunks
• Chat: ~2-5 seconds per query
• Storage: ~13KB per chunk (1024-dim embeddings)

🎯 Trust & Reliability Dashboard

Codehere measures and reports its own reliability. Every operation with --review generates feedback that feeds into trust scores.

Run Analytics

npm run analyze:feedback

Shows trust scores per agent, success rates, and operation breakdowns. See docs/VALIDATION_MODE_USAGE_GUIDE.md for details.

🔒 Security & Privacy

• Local-first storage: All embeddings and feedback stored locally in SQLite – nothing leaves your machine
• No code transmission: Only chunks sent to API for embedding, never full files
• Privacy-first feedback: All AgentFeedback stored locally in data/feedback/agent-feedback.jsonl. No telemetry. Opt out with CODEHERE_FEEDBACK_OPT_OUT=true
• Audit trail: Complete JSONL logging of all operations with full traceability
• Policy enforcement: Line limits, restricted folders, single-file safety checks
• Review gates: Explicit approval required before applying destructive changes

📈 Use Cases

Codehere helps developers, teams, and enterprises in many ways:

For Developers

• Onboard faster: Understand new codebases in hours, not days
• Debug smarter: AI-powered reasoning to find root causes
• Refactor safely: Automatic verification and rollback
• Learn continuously: Get explanations of any code

For Teams

• Better documentation: Auto-generate accurate, up-to-date docs
• Faster code reviews: AI-assisted review catches issues early
• Consistent patterns: Learn and apply team conventions automatically
• Knowledge sharing: Preserve and share patterns across projects

For Enterprises

• Secure by default: Built-in security scanning and audit trails
• Privacy-first: Local processing, code never leaves your machine
• Productivity metrics: Track ROI and developer productivity
• Organizational memory: Build knowledge that survives team changes

See docs/USE_CASES.md for detailed scenarios and examples.

🧪 Testing

See TESTING.md for complete testing guide.

Test Results:

• ✅ Indexing: Working with retry logic
• ✅ Retrieval: 15 chunks with file relationships
• ✅ Chat: Context-aware responses with error recovery
• ✅ Editing: Diff generation and application
• ✅ Policies: All safety checks enforced
• ✅ Logging: Complete audit trail
• ✅ Health: System monitoring operational

📁 Project Structure

agent/
├── src/
│   ├── index.ts      # CLI entrypoint
│   ├── embed.ts      # Repository indexing & embeddings
│   ├── search.ts     # Semantic search & retrieval
│   ├── chat.ts       # Cohere API integration
│   ├── edit.ts       # Diff generation & application
│   ├── policy.ts     # Safety policy enforcement
│   ├── log.ts        # Audit logging
│   ├── types.ts      # Type definitions
│   ├── ui.ts         # CLI UI utilities
│   ├── error-handler.ts  # Enterprise error handling
│   ├── monitoring.ts  # Health checks & metrics
│   └── context.ts    # Enhanced context understanding
├── data/
│   ├── embeddings.sqlite  # Vector database
│   └── logs.jsonl         # Audit log
├── test/             # Test files
├── package.json
├── tsconfig.json
└── README.md

🛠️ Development

# Development mode
npm run dev

# Build
npm run build

# Run tests
npm test

📝 License

MIT License - see LICENSE for details.

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

Built with ❤️ for developers who want AI assistance without sacrificing control.