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.

5.7 KiB Raw Blame History