myCoder

A Coding Agent Harness with governance guardrails. A lightweight, auditable, and extensible AI coding agent framework built in Python. Each component — context building, LLM abstraction, action parsing, guardrail checks, tool execution, and feedback collection — is independently testable with mock LLMs.

Features

• Pipeline State Machine Architecture: ContextBuilder -> LLM Call -> ActionParser -> Guardrail -> Executor -> FeedbackCollector -> loop back
• Governance Guardrails: FileGuard, ScopeGuard, and ShellGuard protect against dangerous operations with configurable rules
• Human-in-the-Loop (HITL): Commands like git push and pip install can be configured to require approval
• Mock LLM Testing: All core mechanisms are testable with deterministic mock LLM, no network dependency
• Secure API Key Management: Keys stored in the OS credential manager via keyring, with .env fallback

Installation

Requires Python 3.10+.

pip install -e .

For development dependencies (including pytest):

pip install -e ".[dev]"

Quick Start

# First-time setup: configure your API key and preferences
mycoder setup

# Check your API key status
mycoder key status

# Run a coding task
mycoder run "fix the broken test in test_user.py"

# Run with custom options
mycoder run "add type hints to all functions" --model gpt-4o --max-iterations 30

Usage

CLI Commands

Configuration

Configuration is loaded from ~/.mycoder/config.yaml (or the platform equivalent). A default config is created on first mycoder setup. You can customize:

• LLM settings: provider, base URL, model, temperature, max tokens
• Guardrail rules: blocked file patterns, blocked shell commands, HITL approval list
• Tool settings: shell timeout, test timeout, max file read size
• Loop settings: max iterations, max context tokens

Configuration priority: CLI arguments > environment variables > config file > defaults.

API Key Security

myCoder takes API key security seriously:

• Primary storage: keyring -> OS credential manager (Windows Credential Manager, macOS Keychain, Linux Secret Service)
• Fallback: .env file with MYCODER_API_KEY environment variable (less secure, warns on use)
• Never hardcoded: API keys are never written to source code, config files, or logs
• Status checks: mycoder key status shows only "configured" or "not configured" — never the plaintext key

Threat Model

Directory Structure

myCoder/
├── pyproject.toml
├── README.md
├── .gitignore
├── .github/workflows/ci.yml
├── src/harness/
│   ├── __init__.py
│   ├── cli.py          # CLI entry point and command handlers
│   ├── config.py       # Configuration dataclasses and YAML loader
│   ├── context.py      # Context builder for LLM messages
│   ├── feedback.py     # Feedback collector for tool results
│   ├── guardrail.py    # FileGuard, ScopeGuard, ShellGuard, and orchestrator
│   ├── llm.py          # LLM abstraction (RealLLM, MockLLM)
│   ├── loop.py         # Agent main loop and stop judge
│   ├── memory.py       # Memory management (conventions, decisions, codebase knowledge)
│   ├── parser.py       # Action parser for LLM JSON responses
│   └── tools.py        # Tool executor (read_file, write_file, shell, run_tests)
└── tests/
    ├── __init__.py
    ├── test_cli.py
    ├── test_config.py
    ├── test_context.py
    ├── test_demo.py
    ├── test_feedback.py
    ├── test_guardrail.py
    ├── test_llm.py
    ├── test_loop.py
    ├── test_memory.py
    ├── test_parser.py
    └── test_tools.py

Architecture

┌─────────────────────────────────────────────────┐
│                   CLI (cli.py)                    │
│   mycoder run | mycoder setup | mycoder key ...   │
└──────────────────────┬──────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────┐
│                Agent Loop (loop.py)               │
│                                                   │
│  ┌──────────┐  ┌──────┐  ┌────────┐  ┌────────┐ │
│  │ Context   │  │ LLM  │  │ Parser │  │ Stop   │ │
│  │ Builder  │→ │ Call │→ │        │→ │ Judge  │ │
│  └──────────┘  └──────┘  └────────┘  └────────┘ │
│       ↑                                    │      │
│       │         ┌──────────┐               │      │
│       │         │ Guardrail│←──────────────┘      │
│       │         └────┬─────┘                      │
│       │              │ allowed/approval            │
│       │         ┌────▼─────┐                      │
│       │         │ Executor │                      │
│       │         └────┬─────┘                      │
│       │              │                            │
│       │         ┌────▼──────┐                     │
│       └─────────│ Feedback   │                    │
│                 │ Collector │                     │
│                 └───────────┘                     │
└──────────────────────────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────┐
│              Infrastructure Layer                 │
│  ┌────────┐  ┌────────┐  ┌────────┐  ┌────────┐ │
│  │ Config │  │ Memory │  │Keyring │  │ Logging│ │
│  │        │  │        │  │        │  │        │ │
│  └────────┘  └────────┘  └────────┘  └────────┘ │
└──────────────────────────────────────────────────┘

Running Tests

pytest tests/ -v

All core mechanism tests use MockLLM and run without network access.

Known Limitations

• Python 3.10+: Requires Python 3.10 or newer.
• keyring on headless Linux: keyring may require additional configuration (e.g., dbus or gnome-keyring) on headless Linux servers. If keyring is unavailable, fall back to the MYCODER_API_KEY environment variable.
• OpenAI-compatible API only: Currently supports LLM providers with OpenAI-compatible chat completions API format.
• Single task mode: Each mycoder run executes one task end-to-end; no REPL or multi-turn conversation mode.

License

MIT