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 and Codex. 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)
  → or executeTask()
    → WorkflowEngine (workflow/engine.ts)
      → runAgent() (agents/runner.ts)
        → callClaude() (claude/client.ts)
          → executeClaudeQuery() (claude/executor.ts via claude/process.ts)

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)
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
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/workflow.yaml (or named workflow)
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 statusPatterns in src/models/schemas.ts. Common statuses: done, blocked, approved, rejected, in_progress, interrupted.

Project Structure

.takt/                    # Project config (logs/ is gitignored)
  workflow.yaml           # Default workflow definition
  workflows/              # Named workflow files
  agents.yaml             # Custom agent definitions
  agents/                 # Agent prompt files (.md)
  prompts/                # Shared prompts
  logs/                   # Session logs

~/.takt/                  # Global config
  config.yaml             # Trusted dirs, default workflow, log level
  workflows/              # Global workflow files

Workflow YAML Schema

name: workflow-name
max_iterations: 10        # Note: snake_case in YAML
initial_step: first-step

steps:
  - name: step-name
    agent: coder              # Built-in agent name
    # or agent_path: ./agents/custom.md  # Custom prompt file
    instruction_template: |
      {task}
      {previous_output}
    transitions:
      - condition: done
        next_step: next-step
      - condition: blocked
        next_step: ABORT
    on_no_status: complete    # complete|continue|stay

TypeScript Notes

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

Command Design Principles

Keep commands minimal. Avoid proliferating commands. One command per concept.

Use a single command with arguments/modes instead of multiple similar commands
Example: /config opens permission mode selection. No need for /sacrifice, /safe, /confirm, etc.
Before adding a new command, consider if existing commands can be extended

5.0 KiB Raw Blame History