gridcode-runtime 0.1.2

Build production AI agents with modular architecture, advanced prompt engineering, and framework-agnostic design (LangGraph/Pydantic-AI)

GridCode Runtime (GCR)

Modular Agentic Architecture (MAA) - An Open-Source Agent Runtime System

---

📚 Complete Documentation | 完整文档（中文）

Quick Links: Quick Start | Alpha Testing | FAQ | API Reference

---

Overview

GridCode Runtime is an open-source, modular, production-ready agent runtime system inspired by Claude Code's prompt engineering patterns. It provides a unified framework for building intelligent agents with support for multiple AI frameworks (LangGraph, Pydantic-AI).

Key Design Goals:

• Framework-agnostic architecture supporting LangGraph and Pydantic-AI
• Production-ready features: state persistence, monitoring, human-in-the-loop
• Claude Code-inspired patterns: 5-phase planning, context-aware reminders, progressive prompt composition

📖 中文文档: GridCode Runtime 中文文档

🎯 Use Cases

GridCode Runtime is ideal for:

• Multi-Agent Systems - Build complex agent workflows with specialized sub-agents (explore, plan, review)
• Advanced Prompt Engineering - Leverage 100+ reusable templates with dynamic variable resolution
• Framework-Agnostic Development - Switch between LangGraph and Pydantic-AI without code changes
• Production AI Applications - State persistence, monitoring, and human-in-the-loop workflows
• Plugin Development - Extend functionality with custom plugins and MCP server integration
• Code Analysis & Generation - Specialized agents for codebase exploration, planning, and review

✨ Key Features

🎯 Core Capabilities

• Advanced Prompt System: 100+ reusable prompt templates with 4-type variable injection (${VAR}, ${context.prop}, ${COND ? "A" : "B"}, ${FUNC()})
• Framework Agnostic: Nexus Agent Engine with Strategy+Adapter patterns supporting LangGraph and Pydantic-AI
• Multi-Agent Architecture: 10 specialized agents (Main, Explore, Plan, Review, TestRunner, Architect, CodeReviewer, Debugger, DocsArchitect, APIDocumenter, TutorialEngineer)
• 5-Phase Planning Workflow: Understanding → Exploration → Planning → Review → Ready
• Context-Aware System Reminders: 18+ dynamic system hints with 5 Learning Mode reminders
• Learning Mode: Continuous improvement with FeedbackRecord, pattern analysis, and knowledge accumulation
• Plugin System: 5 plugin types with 10+ hook events and auto-discovery

🚀 Production Features

• State Persistence: SQLite-based checkpoints with ExecutionContext management
• Human-in-the-Loop: ConsoleInteractionHandler with approval workflows
• Tool Result Enhancement: Automatic guidance injection via ToolResultEnhancer
• Layered Permissions: Agent-specific tool whitelists/blacklists (main/explore/plan/review)
• MCP Integration: Multi-server support with stdio/HTTP transports and connection pooling
• Configuration System: YAML/environment/CLI with validation and templates

Architecture

GridCode Runtime adopts a three-layer architecture with clear separation of concerns:

┌─────────────────────────────────────────────────────────────┐
│  Layer 3: Orchestration                                     │
│  - GridCodeRuntime: Main runtime coordinator                │
│  - PlanModeManager: 5-phase planning workflow               │
│  - LearningModeManager: Learning mode & feedback system     │
└─────────────────────────────────────────────────────────────┘
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  Layer 2: Execution                                         │
│  ┌─────────────────────┐  ┌───────────────────────────────┐ │
│  │  Nexus Agent Engine │  │  Prompt Composer              │ │
│  │  (LangGraph/PAI)    │  │  (Template + Variable System) │ │
│  └─────────────────────┘  └───────────────────────────────┘ │
│  ┌─────────────────────┐  ┌───────────────────────────────┐ │
│  │  Agent Pool         │  │  Tool Registry                │ │
│  │  (10 Specialized)   │  │  (Read/Write/Edit/Glob/Grep)  │ │
│  └─────────────────────┘  └───────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  Layer 1: Foundation                                        │
│  - ExecutionContext: State management (session/agent/tool)  │
│  - SQLiteStorage: Context persistence                       │
│  - PluginManager: Plugin system & hook registry             │
│  - MCPClient: MCP server integration                        │
└─────────────────────────────────────────────────────────────┘

🚀 Quick Start

Installation

# Basic installation (core features only)
pip install gridcode-runtime

# With LangGraph support (recommended for production)
pip install 'gridcode-runtime[langgraph]'

# With Pydantic-AI support
pip install 'gridcode-runtime[pydantic-ai]'

# With all optional dependencies (LangGraph + Pydantic-AI + dev tools)
pip install 'gridcode-runtime[all]'

Optional Dependencies

GridCode Runtime supports multiple agent frameworks through optional dependencies:

Extra	Includes	Use Case
langgraph	LangGraph >= 0.2.0, langchain-core, langchain-anthropic	Production multi-agent workflows
pydantic-ai	Pydantic-AI >= 0.0.13	Type-safe agent development
all	All frameworks + dev tools	Development and testing

Note: The core package works without optional dependencies, but framework-specific features require the corresponding extras.

Basic Usage

import asyncio
from gridcode.core import GridCodeRuntime, ExecutionContext

async def main():
    # Create runtime with LangGraph adapter
    runtime = GridCodeRuntime(
        api_key="your-anthropic-api-key",
        framework="langgraph"  # or "pydantic-ai"
    )

    # Setup execution context
    context = ExecutionContext(
        session_id="demo-session",
        working_dir="/path/to/project"
    )

    # Run agent with simple prompt
    result = await runtime.run(
        prompt="Analyze this project's code structure",
        context=context
    )
    print(result.content)

asyncio.run(main())

CLI Usage

# Run agent with CLI
gridcode run "Analyze code structure" --framework langgraph

# Configure settings
gridcode config set anthropic.api_key "your-api-key"
gridcode config set runtime.framework "langgraph"

# List available plugins
gridcode plugins list

# Get plugin information
gridcode plugins info example-plugin

📖 Advanced Usage

Using Sub-Agents

from gridcode.agents import AgentPool

# Initialize agent pool
pool = AgentPool(
    framework="langgraph",
    api_key="your-api-key"
)

# Spawn explore agent for read-only codebase exploration
result = await pool.spawn_agent(
    agent_type="explore",
    task="Find all API endpoint definitions",
    context=context
)

# Spawn plan agent for planning without execution
plan = await pool.spawn_agent(
    agent_type="plan",
    task="Design a new authentication system",
    context=context
)

Enabling Learning Mode

from gridcode.workflows import LearningModeManager

# Enable learning mode for continuous improvement
learning_mgr = LearningModeManager(context)
learning_mgr.enable()

# Provide feedback after task completion
learning_mgr.record_feedback(
    task_id="task-123",
    rating=5,
    feedback="Great performance on API analysis"
)

# Get learned patterns
patterns = learning_mgr.get_patterns()

Plugin Development

from gridcode.plugins import Plugin, Hook

class MyPlugin(Plugin):
    name = "my-plugin"
    version = "1.0.0"

    @Hook.on("PreToolUse")
    async def before_tool_use(self, tool_name: str, args: dict):
        # Custom logic before tool execution
        print(f"About to use tool: {tool_name}")
        return True  # Allow execution

    @Hook.on("PostToolUse")
    async def after_tool_use(self, tool_name: str, result: any):
        # Custom logic after tool execution
        print(f"Tool {tool_name} completed")

⚙️ Configuration

GridCode can be configured via YAML file, environment variables, or CLI arguments.

Configuration File

Create gridcode.yaml in your project directory:

runtime:
  api_provider: anthropic
  api_key: ${ANTHROPIC_API_KEY}
  model: claude-sonnet-4-5
  framework: langgraph

agent_pool:
  cache_enabled: true
  max_agents: 5

mcp:
  enabled: true
  servers:
    - name: context7
      type: stdio
      command: npx
      args: ["-y", "@context7/mcp-server"]
      env:
        CONTEXT7_API_KEY: ${CONTEXT7_API_KEY}

plugins:
  enabled: true
  dirs:
    - ~/.gridcode/plugins
    - ./plugins

For full configuration options, see gridcode.yaml.template or the Configuration Guide.

Environment Variables

# API Keys
export ANTHROPIC_API_KEY="sk-ant-xxx"
export OPENAI_API_KEY="sk-proj-xxx"

# Optional: Model selection
export OPENAI_MODEL_NAME="gpt-4"

# Optional: MCP servers
export CONTEXT7_API_KEY="c7-xxx"

CLI Options

# Use custom config file
gridcode run --config custom.yaml "Your query"

# Override config with CLI args
gridcode run --model gpt-4 --api-key sk-xxx "Your query"

# Configuration priority: CLI args > Environment variables > Config file > Defaults

🧪 Testing

GridCode has comprehensive test coverage with unit tests, integration tests, and performance benchmarks.

Run Tests

# All tests
pytest

# Unit tests only (fast)
pytest tests/unit/ -v

# Integration tests (with mocked APIs)
pytest tests/integration/ --run-integration

# With coverage
pytest --cov=src --cov-report=term-missing

# Generate HTML coverage report
pytest --cov=src --cov-report=html
open htmlcov/index.html

Test Status

• Total Tests: 822 tests
• Passing: 822 (100%)
• Coverage: 81%
• Test Categories:
  • Unit tests: ~697 tests (core logic)
  • Integration tests: ~125 tests (E2E scenarios)

For more details, see the Testing Guide.

📚 Documentation

📖 Getting Started

• Alpha Testing Guide - Get started with alpha testing
• FAQ - Frequently asked questions and troubleshooting
• Quick Start Guide - Get up and running in 5 minutes
• Configuration Guide - Complete configuration reference

🏗️ Architecture & Design

• Architecture Overview - Three-layer system architecture and design patterns
• Nexus Agent Engine - Framework adapter design (Strategy + Adapter patterns)
• Prompt System Design - Template composition and variable resolution
• Plugin System - Extensible plugin architecture with hooks

📖 User Guides

• Agent Usage Guide - Working with multi-agent workflows
• CLI Reference - Complete CLI command reference
• Plugin Development - Creating custom plugins and hooks

🛠️ Developer Guides

• Contributing Guide - How to contribute to the project
• API Reference - Complete API documentation
• Testing Guide - Testing strategies and best practices

🌏 中文文档

• Alpha 测试指南 - Alpha 版本测试指南
• 常见问题解答 - 常见问题和解决方案
• 完整中文文档 - 完整的中文版 README

Core Design Patterns (from Claude Code)

Pattern	Description
Progressive Prompt Composition	Layer prompts based on task complexity
5-Phase Planning Workflow	Explore → Design → Review → Finalize → Approve
Context-Aware Reminders	Dynamic system hints based on state
Layered Tool Permissions	Different capabilities per agent type
Tool Result Enhancement	Inject guidance in tool responses

🛠️ Tech Stack

Category	Technologies
Runtime	Python 3.11+, asyncio
AI Frameworks	LangGraph 0.2+, Pydantic-AI 0.0.13+
LLM Client	Anthropic Claude API (Sonnet 4.5, Opus 4.5)
Storage	SQLite (checkpoints), Redis (optional)
CLI	Typer, Rich
Logging	loguru
Testing	pytest, pytest-asyncio, pytest-cov
Code Quality	Black, isort, Ruff, mypy

🗺️ Roadmap

Phase 1-3: Foundation ✅ (Complete)

• Prompt Composer with variable resolution
• Nexus Agent Engine (LangGraph + Pydantic-AI adapters)
• Agent Pool (Explore, Plan, Review agents)
• 5-Phase Planning Workflow
• System Reminders (18+ reminder types)
• Context Persistence (SQLite)

Phase 4: Ecosystem ✅ (Complete)

• Learning Mode with feedback system
• Plugin System with hook registry
• MCP Integration
• Plugin Discovery & Auto-loading

Phase 5: Production ✅ (Complete)

• CLI Interface (typer-based)
• Performance Optimization (lazy loading, caching)
• Memory Profiling & Leak Detection
• Configuration System (gridcode.yaml)
• Integration Tests (131 E2E tests, 99.3% pass rate)
• Documentation (Configuration Guide, Testing Guide)

Phase 6: Future 🔮 (Planned)

• Web UI for agent monitoring
• More framework adapters (AutoGen, CrewAI)
• Distributed agent orchestration
• Cloud deployment support

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for:

• Development environment setup
• Code style guidelines
• Testing requirements
• Pull request process

📄 License

This project is licensed under the MIT License - see LICENSE for details.

🙏 Acknowledgments

This project is inspired by Claude Code's prompt engineering patterns. Special thanks to the Anthropic team for their innovative work in agentic AI systems.

📧 Contact & Support

• Alpha Testing: Alpha Testing Guide
• FAQ: Frequently Asked Questions
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• 中文支持: 中文文档 | 中文 FAQ