TAKT

Task Agent Koordination Tool - Multi-agent orchestration system for Claude Code (Codex support planned).

Note

: This project is developed at my own pace. See Disclaimer for details.

Requirements

• Claude Code must be installed and configured

Installation

npm install -g takt

Quick Start

# Run a task (will prompt for workflow selection)
takt "Add a login feature"

# Switch workflow
takt /switch

# Run all pending tasks
takt /run-tasks

Commands

Command	Description
takt "task"	Execute task with workflow selection
takt -r "task"	Execute task, resuming previous session
takt /run-tasks	Run all pending tasks
takt /switch	Switch workflow interactively
takt /clear	Clear agent conversation sessions
takt /help	Show help

Workflows

TAKT uses YAML-based workflow definitions. Place them in:

• ~/.takt/workflows/*.yaml

Example Workflow

name: default
max_iterations: 10

steps:
  - name: implement
    agent: coder
    instruction_template: |
      {task}
    transitions:
      - condition: done
        next_step: review
      - condition: blocked
        next_step: ABORT

  - name: review
    agent: architect
    transitions:
      - condition: approved
        next_step: COMPLETE
      - condition: rejected
        next_step: implement

Built-in Agents

• coder - Implements features and fixes bugs
• architect - Reviews code and provides feedback
• supervisor - Final verification and approval

Custom Agents

Define custom agents in .takt/agents.yaml:

agents:
  - name: my-reviewer
    prompt_file: .takt/prompts/reviewer.md
    allowed_tools: [Read, Glob, Grep]
    status_patterns:
      approved: "\\[APPROVE\\]"
      rejected: "\\[REJECT\\]"

Project Structure

~/.takt/
├── config.yaml          # Global config
├── workflows/           # Workflow definitions
└── agents/              # Agent prompt files

Practical Usage Guide

Resuming Sessions with -r

When TAKT prompts for additional input during execution (e.g., "Please provide more details"), use the -r flag to continue the conversation:

# First run - agent might ask for clarification
takt "Fix the login bug"

# Resume the same session to provide the requested information
takt -r "The bug occurs when the password contains special characters"

The -r flag preserves the agent's conversation history, allowing for natural back-and-forth interaction.

Playing with MAGI System

MAGI is a deliberation system inspired by Evangelion. Three AI personas analyze your question from different perspectives and vote:

# Select 'magi' workflow when prompted
takt "Should we migrate from REST to GraphQL?"

The three MAGI personas:

• MELCHIOR-1 (Scientist): Logical, data-driven analysis
• BALTHASAR-2 (Nurturer): Team and human-centered perspective
• CASPER-3 (Pragmatist): Practical, real-world considerations

Each persona votes: APPROVE, REJECT, or CONDITIONAL. The final decision is made by majority vote.

Adding Custom Workflows

Create your own workflow by adding YAML files to ~/.takt/workflows/:

# ~/.takt/workflows/my-workflow.yaml
name: my-workflow
description: My custom workflow

max_iterations: 5

steps:
  - name: analyze
    agent: ~/.takt/agents/my-agents/analyzer.md
    instruction_template: |
      Analyze this request: {task}
    transitions:
      - condition: done
        next_step: implement

  - name: implement
    agent: ~/.takt/agents/default/coder.md
    instruction_template: |
      Implement based on the analysis: {previous_response}
    pass_previous_response: true
    transitions:
      - condition: done
        next_step: COMPLETE

Specifying Agents by Path

Agents are specified using file paths in workflow definitions:

# Use built-in agents
agent: ~/.takt/agents/default/coder.md
agent: ~/.takt/agents/magi/melchior.md

# Use project-local agents
agent: ./.takt/agents/my-reviewer.md

# Use absolute paths
agent: /path/to/custom/agent.md

Create custom agent prompts as Markdown files:

# ~/.takt/agents/my-agents/reviewer.md

You are a code reviewer focused on security.

## Your Role
- Check for security vulnerabilities
- Verify input validation
- Review authentication logic

## Output Format
- [REVIEWER:APPROVE] if code is secure
- [REVIEWER:REJECT] if issues found (list them)

Using /run-tasks for Batch Processing

The /run-tasks command executes all task files in .takt/tasks/ directory:

# Create task files as you think of them
echo "Add unit tests for the auth module" > .takt/tasks/001-add-tests.md
echo "Refactor the database layer" > .takt/tasks/002-refactor-db.md
echo "Update API documentation" > .takt/tasks/003-update-docs.md

# Run all pending tasks
takt /run-tasks

How it works:

• Tasks are executed in alphabetical order (use prefixes like 001-, 002- for ordering)
• Each task file should contain a description of what needs to be done
• Completed tasks are moved to .takt/completed/ with execution reports
• New tasks added during execution will be picked up dynamically

Task file format:

# .takt/tasks/add-login-feature.md

Add a login feature to the application.

Requirements:
- Username and password fields
- Form validation
- Error handling for failed attempts

This is perfect for:

• Brainstorming sessions where you capture ideas as files
• Breaking down large features into smaller tasks
• Automated pipelines that generate task files

Workflow Variables

Available variables in instruction_template:

Variable	Description
{task}	Original user request
{iteration}	Current iteration number
{max_iterations}	Maximum iterations
{previous_response}	Previous step's output (requires pass_previous_response: true)
{user_inputs}	Additional user inputs during workflow
{git_diff}	Current git diff (uncommitted changes)

API Usage

import { WorkflowEngine, loadWorkflow } from 'takt';  // npm install takt

const config = loadWorkflow('default');
if (!config) {
  throw new Error('Workflow not found');
}
const engine = new WorkflowEngine(config, process.cwd(), 'My task');

engine.on('step:complete', (step, response) => {
  console.log(`${step.name}: ${response.status}`);
});

await engine.run();

Disclaimer

This project is a personal project developed at my own pace.

• Response times: I may not be able to respond to issues immediately
• Development style: This project is primarily developed using "vibe coding" (AI-assisted development) - use at your own risk
• Pull requests:
  • Small, focused PRs (bug fixes, typos, docs) are welcome
  • Large PRs, especially AI-generated bulk changes, are difficult to review

See CONTRIBUTING.md for more details.

Docker Support

Docker environment is provided for testing in other environments:

# Build Docker images
docker compose build

# Run tests in container
docker compose run --rm test

# Run lint in container
docker compose run --rm lint

# Build only (skip tests)
docker compose run --rm build

This ensures the project works correctly in a clean Node.js 20 environment.

Documentation

• 🇯🇵 日本語ドキュメント - Japanese documentation
• Workflow Guide - Create and customize workflows
• Agent Guide - Configure custom agents
• Changelog - Version history
• Security Policy - Vulnerability reporting

License

MIT - See LICENSE for details.