Spaces:
Sleeping
Sleeping
File size: 4,637 Bytes
116524e | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 | # Claude Code Integration
The `ClaudeCode` runner wraps the [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) 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
```python
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
```bash
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
```python
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
1. **INJECT** — Skillbook strategies are appended to the task prompt passed to Claude Code for that run
2. **EXECUTE** — Claude Code CLI runs the task in the project directory
3. **Extract trace** — ACE parses Claude Code's `--output-format=stream-json` transcript into a learning trace
4. **LEARN** — Reflector analyzes the trace, SkillManager updates the skillbook
The stock `ClaudeCode` runner does **not** wire `PersistStep`, so it does not
update `CLAUDE.md` automatically. Persist learned strategies with
`runner.save(...)`, or compose a custom pipeline that adds `PersistStep` if you
want file-based prompt injection outside the runner.
## 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:
```bash
kayba setup
```
This copies the skill into `.claude/skills/kayba-pipeline/`. The pipeline stages are:
1. **Analyze traces** — extract patterns from agent execution transcripts
2. **Compute metrics** — score traces against quality dimensions
3. **Build rubric** — generate a structured evaluation rubric
4. **Plan fixes** — propose concrete improvements
5. **HITL review** — optional human-in-the-loop approval gate
6. **Apply fixes** — execute the approved changes
7. **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](hosted-api.md#agent-setup) 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
```python
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
```python
runner = ClaudeCode.from_model(
working_dir="./my_project",
skillbook_path="coding_expert.json",
)
```
## What to Read Next
- [Integration Pattern](../guides/integration.md) — how the INJECT/EXECUTE/LEARN pattern works
- [The Skillbook](../concepts/skillbook.md) — how learned strategies are stored
|