GitHub - wolvever/codin: Coding agent

Codin - AI Coding Agent Framework

A modern, extensible framework for building AI coding agents with support for multiple LLM providers, tool systems, and execution environments.

Features

Multi-LLM Support: OpenAI, Anthropic, Google Gemini, and more
Tool System: Extensible tool registry with built-in coding tools
Sandbox Environments: Local and containerized execution
Memory Management: Conversation history and context management
Agent Architecture: Modular agent design with planners and executors
Plan-Execute Agent: Simple planner that generates a plan then executes each step
A2A Protocol: Compatible with Agent-to-Agent communication standards

Quick Start

Hello World Example

The framework includes a complete hello world example demonstrating the BaseAgent + CodePlanner architecture:

# Run with mock LLM (no API keys required)
python examples/hello_world_test.py

# Run with real LLM (requires API keys)
python examples/hello_world.py

This example demonstrates:

BaseAgent + CodePlanner iterative execution loop
Tool execution (file creation, shell commands)
Task completion logic
Memory and state management

Agent Logic Comparison

The framework implements the same core iterative loop logic as other coding agents:

Component	BaseAgent + CodePlanner	CodeAgent	Codex.rs
Loop Driver	Planner step generation	Tool call presence	Function call presence
Completion Logic	FinishStep from planner	should_continue flag + heuristics	Empty function call list
State Management	Immutable State + Memory service	Mutable instance variables	Mutex-protected state
Tool Execution	Step-based via ToolCallStep	Turn-based with results	Stream-based function calls

See docs/agent_architecture.md for a deeper explanation of the agent loop and state handling.

Installation

# Clone the repository
git clone <repository-url>
cd codin

# Install with uv (recommended)
uv sync

# Or install with pip (development mode)
pip install -e .[dev]

Environment Setup

Copy .env-example to .env and configure your API keys:

cp .env-example .env
# Edit .env with your API keys

Usage

Basic Agent Setup

from codin.agent.base_agent import BaseAgent
from codin.agent.code_planner import CodePlanner, CodePlannerConfig
from codin.tool.registry import ToolRegistry
from codin.tool import SandboxToolset
from codin.sandbox.local import LocalSandbox

# Initialize components
sandbox = LocalSandbox()
await sandbox.up()

tool_registry = ToolRegistry()
sandbox_toolset = SandboxToolset(sandbox)
await sandbox_toolset.up()
tool_registry.register_toolset(sandbox_toolset)

# Create planner and agent
planner_config = CodePlannerConfig(model="gpt-4")
planner = CodePlanner(config=planner_config, tool_registry=tool_registry)

agent = BaseAgent(
    name="CodingAgent",
    planner=planner,
    tools=tool_registry.get_tools()
)

# Execute task
from codin.agent.types import AgentRunInput, Message
from codin.agent.types import Role, TextPart

task_message = Message(
    messageId="task-1",
    role=Role.user,
    parts=[TextPart(text="Create a Python hello world script")],
    contextId="session-1",
    kind="message"
)

agent_input = AgentRunInput(
    session_id="session-1",
    message=task_message
)

async for output in agent.run(agent_input):
    print(f"Agent output: {output}")

CLI Tools

CoDIN provides powerful CLI tools for development workflows:

# Code review with AI
python -m codin.cli review --file src/main.py --project myapp

# System architecture design
python -m codin.cli architect --requirements "Build REST API with auth"

# Test generation
python -m codin.cli test --target UserService --file user_service.py

# Interactive development session
python -m codin.cli repl --agent code_agent

# Run agent on specific task
python -m codin.cli run --agent plan_execute --task "Implement user authentication"

Debug Sandbox

Run commands under the same sandbox used by Codin:

codin debug-sandbox --full-auto echo "hello sandbox"
codin debug-sandbox -s disk-write-cwd -s network-full-access -- python script.py

Use -s/--sandbox-permission multiple times to customize the policy or --full-auto for a permissive default.

Architecture

The framework follows a modular architecture:

Agents: High-level orchestrators (BaseAgent)
Planners: LLM-based step generation (CodePlanner)
Tools: Extensible tool system with registries
Sandbox: Execution environments (Local, Docker)
Memory: Conversation and context management
Models: LLM abstraction layer

Contributing

Fork the repository
Create a feature branch
Make your changes
Install dependencies with pip install -e . (or uv sync)
Add tests for new functionality
Run the test suite: pytest
Submit a pull request

License

[License information]