CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

TAKT (Task Agent Koordination Tool) is a multi-agent orchestration system for Claude Code. It enables YAML-based workflow definitions that coordinate multiple AI agents through state machine transitions.

Commands

Command	Description
`npm run build`	TypeScript build
`npm run test`	Run all tests
`npm run test:watch`	Watch mode
`npm run lint`	ESLint
`npx vitest run src/__tests__/client.test.ts`	Run single test file
`npx vitest run -t "pattern"`	Run tests matching pattern

Architecture

Core Flow

CLI (cli.ts)
  → Slash commands (/run-tasks, /switch, /clear, /help, /config)
  → or executeTask()
    → WorkflowEngine (workflow/engine.ts)
      → runAgent() (agents/runner.ts)
        → callClaude() (claude/client.ts)
          → executeClaudeCli() (claude/process.ts)
            → ClaudeProcess (claude-agent-sdk)

Key Components

WorkflowEngine (src/workflow/engine.ts)

State machine that orchestrates agent execution via EventEmitter
Manages step transitions based on agent response status
Emits events: step:start, step:complete, step:blocked, step:loop_detected, workflow:complete, workflow:abort, iteration:limit
Supports loop detection (LoopDetector) and iteration limits
Maintains agent sessions per step for conversation continuity

Agent Runner (src/agents/runner.ts)

Resolves agent specs (name or path) to agent configurations
Built-in agents with default tools:
- coder: Read/Glob/Grep/Edit/Write/Bash/WebSearch/WebFetch
- architect: Read/Glob/Grep/WebSearch/WebFetch
- supervisor: Read/Glob/Grep/Bash/WebSearch/WebFetch
- planner: Read/Glob/Grep/Bash/WebSearch/WebFetch
Custom agents via .takt/agents.yaml or prompt files (.md)
Supports Claude Code agents (claudeAgent) and skills (claudeSkill)

Claude Integration (src/claude/)

client.ts - High-level API: callClaude(), callClaudeCustom(), callClaudeAgent(), callClaudeSkill(), status detection via regex patterns
process.ts - SDK wrapper with ClaudeProcess class, re-exports query management
executor.ts - Query execution using @anthropic-ai/claude-agent-sdk
query-manager.ts - Concurrent query tracking with query IDs

Configuration (src/config/)

loader.ts - Custom agent loading from .takt/agents.yaml
workflowLoader.ts - YAML workflow parsing with Zod validation (loads from ~/.takt/workflows/ only)
agentLoader.ts - Agent prompt file loading
paths.ts - Directory structure (.takt/, ~/.takt/), session management

Data Flow

User provides task or slash command → CLI
CLI loads workflow from ~/.takt/workflows/{name}.yaml
WorkflowEngine starts at initialStep
Each step: buildInstruction() → runStep() → runAgent() → callClaude() → detect status → determineNextStep()
Status patterns (regex in statusPatterns) determine next step via transitions
Special transitions: COMPLETE ends workflow successfully, ABORT ends with failure

Status Detection

Agents output status markers (e.g., [CODER:DONE]) that are matched against GENERIC_STATUS_PATTERNS in src/models/schemas.ts. Common statuses: done, blocked, approved, rejected, improve, in_progress, interrupted.

Directory Structure

~/.takt/                  # Global user config (created on first run)
  config.yaml             # Trusted dirs, default workflow, log level, language
  workflows/              # Workflow YAML files (required location)
  agents/                 # Agent prompt files (.md)

.takt/                    # Project-level config
  agents.yaml             # Custom agent definitions
  tasks/                  # Task files for /run-tasks
  reports/                # Execution reports (auto-generated)
  logs/                   # Session logs (gitignored)

resources/                # Bundled defaults (copied to ~/.takt on init)
  global/
    en/                   # English agents and workflows
    ja/                   # Japanese agents and workflows

Workflow YAML Schema

name: workflow-name
description: Optional description
max_iterations: 10        # snake_case in YAML

steps:
  - name: step-name
    agent: ~/.takt/agents/default/coder.md  # Path to agent prompt
    agent_name: coder                       # Display name (optional)
    instruction_template: |
      {task}
      {previous_response}
    pass_previous_response: true            # Default: true
    transitions:
      - condition: done
        next_step: next-step
      - condition: blocked
        next_step: ABORT
    on_no_status: complete    # complete|continue|stay

Template Variables

Variable	Description
`{task}`	Original user request
`{iteration}`	Current iteration number
`{max_iterations}`	Maximum iterations
`{previous_response}`	Previous step output (requires `pass_previous_response: true`)
`{user_inputs}`	Accumulated user inputs during workflow
`{git_diff}`	Current git diff (uncommitted changes)
`{report_dir}`	Report directory name (e.g., `20250126-143052-task-summary`)

TypeScript Notes

ESM modules with .js extensions in imports
Strict TypeScript with noUncheckedIndexedAccess
Zod schemas (v4 syntax) for runtime validation (src/models/schemas.ts)
Uses @anthropic-ai/claude-agent-sdk for Claude integration

Design Principles

Keep commands minimal. One command per concept. Use arguments/modes instead of multiple similar commands. Before adding a new command, consider if existing commands can be extended.

Do NOT expand schemas carelessly. The TransitionConditionSchema defines allowed condition values for workflow transitions. Do NOT add new values without strong justification. Use existing values creatively:

done - Task completed (minor fixes, successful completion)
blocked - Cannot proceed (needs plan rework)
approved - Review passed
rejected - Review failed, needs major rework
improve - Needs improvement (security concerns, quality issues)
always - Unconditional transition

6.2 KiB Raw Blame History