Claude Code Integration

The ClaudeCode runner wraps the Claude Code CLI with ACE learning. The agent runs coding tasks in your project directory and learns strategies from each execution — improving code generation, debugging, and project-specific patterns over time.

Quick Start

from ace import ClaudeCode

runner = ClaudeCode.from_model(working_dir="./my_project")

results = runner.run("Add unit tests for utils.py")
runner.save("coding_expert.json")

Installation

uv add ace-framework[claude-code]

Prerequisites

Claude Code CLI installed and authenticated
A project directory with source code

Parameters

from_model()

Parameter	Type	Default	Description
`working_dir`	`str`	`None`	Path to the project directory
`ace_model`	`str`	`"gpt-4o-mini"`	Model for Reflector + SkillManager
`ace_max_tokens`	`int`	`2048`	Max tokens for ACE LLM responses
`ace_temperature`	`float`	`0.0`	Sampling temperature for ACE roles

from_roles()

Parameter	Type	Default	Description
`reflector`	`ReflectorLike`	—	Reflector instance
`skill_manager`	`SkillManagerLike`	—	SkillManager instance
`working_dir`	`str`	`None`	Project directory
`timeout`	`int`	`600`	Execution timeout (seconds)
`model`	`str`	`None`	Claude model override
`allowed_tools`	`list[str]`	`None`	Allowed Claude Code tools
`skillbook_path`	`str`	`None`	Load saved skillbook
`dedup_config`	`DeduplicationConfig`	`None`	Deduplication config
`checkpoint_dir`	`str`	`None`	Checkpoint directory

Methods

results = runner.run(tasks, epochs=1)       # Run with learning
runner.save("path.json")                    # Save skillbook
runner.wait_for_background()                # Wait for async learning
runner.get_strategies()                     # View learned strategies

How It Works

INJECT — Skillbook strategies are written to CLAUDE.md at the project root
EXECUTE — Claude Code CLI runs the task in the project directory
Extract trace — ACE reads the Claude Code execution transcript
LEARN — Reflector analyzes the trace, SkillManager updates the skillbook

Pipeline Skill

The kayba-pipeline skill gives Claude Code a 7-stage evaluation and improvement pipeline that can be triggered directly from the chat. Install it with:

kayba setup

This copies the skill into .claude/skills/kayba-pipeline/. The pipeline stages are:

Analyze traces — extract patterns from agent execution transcripts
Compute metrics — score traces against quality dimensions
Build rubric — generate a structured evaluation rubric
Plan fixes — propose concrete improvements
HITL review — optional human-in-the-loop approval gate
Apply fixes — execute the approved changes
Verify — confirm fixes pass the rubric

Trigger the pipeline by saying "run the pipeline" or "kayba pipeline" in Claude Code with a traces folder in your project.

To skip skill installation: kayba setup --no-skills. See Hosted API for all kayba setup options.

How It Works (continued)

The agent learns project-specific patterns like:

Code style and conventions
Common debugging approaches
Test patterns and frameworks used
Module structure and dependencies

Running Multiple Tasks

results = runner.run([
    "Add unit tests for utils.py",
    "Fix the bug in the login handler",
    "Refactor the database module to use connection pooling",
])

Resuming from a Saved Skillbook

runner = ClaudeCode.from_model(
    working_dir="./my_project",
    skillbook_path="coding_expert.json",
)