████████  ██████  ██    ██  ██    ██    ████
   ██    ██       ██    ██  ██   ██    ██  ██
   ██     ██████  ██    ██  ██████    ████████
   ██          ██ ██    ██  ██   ██   ██    ██
   ██    ██████    ██████   ██    ██  ██    ██

TSUKA is a deterministic, lightweight multi-agent harness and interactive CLI/TUI written entirely in TypeScript. It connects seamlessly to local LLM engines (Ollama, llama.cpp/llama-server, Unsloth Studio, LM Studio) via standard OpenAI-compatible endpoints (/v1/chat/completions) and cloud gateways (OpenRouter).

🗡️ The name: 柄 (tsuka) is the katana's hilt — the foundational grip where every blade mounts. Your models are the blades; TSUKA is the harness that lets you wield them with precision and safety.

💡 Why TSUKA? Most multi-agent systems are heavy, opaque, Python/Linux-centric frameworks. TSUKA brings deterministic, inspectable agentic orchestration to Windows (PowerShell), Linux, and macOS with zero boilerplate, hot-pluggable tools, persistent memory, and a rich terminal interface.

• ⚡ Quickstart in 60 Seconds
• 🚀 Installation & Setup
• 🖥️ Interactive Terminal UI (TUI Dashboard)
• 👥 Multi-Agent Workflows
  • Dynamic Goal Orchestrator (/goal)
  • Collaborative Teams (/team)
  • Conference Debate (/call)
  • Coordination Protocol & Blackboard
• 🔁 Verify $\to$ Correct Loop & Anti-Stall
• 🧰 Tool Catalog (27 Native Tools)
  • Tool Self-Authoring (create_tool)
• 🛡️ Security & 3-Tier Permissions
• 📊 Model Fingerprinting & Benchmarks
• 🛠️ REPL Slash Commands Reference
• 🏗️ Architecture & Concepts
• 🧪 Testing & Verification
• 📚 Documentation & Wiki
• 🗺️ Roadmap & Contributing
• 📄 License

# 1. Clone the repository and install dependencies
git clone https://github.com/nispa/tsuka.git
cd tsuka
npm install
npm run build
npm link             # Exposes the global `tsuka` command

# 2. Initialize workspace with the core agent roster
tsuka init --preset core

# 3. Launch interactive terminal interface
npm run tui          # Full-screen TUI dashboard (or: tsuka --tui)
# Or standard CLI REPL:
tsuka

Download and start your preferred LLM provider:

# Option A: Ollama
ollama serve
ollama pull qwen2.5-coder:7b

# Option B: llama.cpp / llama-server
llama-server -m models/qwen2.5-coder-7b.gguf --port 8080

# Option C: Cloud API (OpenRouter)
echo "OPENROUTER_API_KEY=your_key_here" >> .env

Run TSUKA from any directory in PowerShell, Bash, or Zsh:

npm run build
npm link             # Registers `tsuka` globally on your PATH
tsuka                # Launch REPL anywhere
tsuka --tui          # Launch full-screen TUI anywhere

To refresh after local source modifications, run npm run build. To uninstall: npm unlink -g tsuka.

Initialize isolated project workspaces with tailored agent rosters:

tsuka init                         # Interactive setup wizard
tsuka init --preset core           # Core roster (14 characters, 4 teams)
tsuka init --preset full           # Full roster (all 24 characters, 21 roles, 10 teams)
tsuka init --pack osint,devops     # Add specific domain packs from presets/packs/
tsuka init --force                 # Overwrite existing .tsuka/ directory

TSUKA resolves resources hierarchically (src/core/apphome.ts):

1. Workspace .tsuka/: If present in the current launch directory, project-specific memory, characters, and configs take precedence.
2. App Home Fallback: Falls back to the global installation directory (or $env:TSUKA_HOME).
3. Workspace Root: Relative filesystem operations (read_file, write_file, grep_search) always anchor safely inside the launch folder.

TSUKA includes a zero-flicker terminal dashboard built without heavy web wrappers:

npm run tui
# or:
tsuka --tui

┌─ TSUKA v0.5.1 ── [F1] Chat  [F2] Tools ─────────────────── [Ctx: 2,410 / 32,768 (7%)] ─┐
│ 📁 Explorer       │ 💬 Active Agent: @geordi (Developer)                               │
│ ├─ src/           │                                                                    │
│ │  ├─ core/       │ User: Build a file hasher utility and test it.                     │
│ │  └─ tools/      │                                                                    │
│ ├─ package.json   │ 🧠 Thinking: Planning modular hash implementation...               │
│ └─ tsuka.config   │ ⚡ [PREFILL 140 tok] 🌊 [DECODE 84.2 tok/s] [TTFT 120ms]           │
│                   │ 🛠️  write_file -> src/hasher.ts (SUCCESS)                         │
│ ⚡ Telemetry       │                                                                    │
│ Dec: 84.2 tok/s   │ Assistant: Created src/hasher.ts with SHA-256 support.             │
│ Conf: [████████░] │                                                                    │
├───────────────────┴────────────────────────────────────────────────────────────────────┤
│ > Run tests to verify the hasher implementation...                                     │
└────────────────────────────────────────────────────────────────────────────────────────┘

TSUKA offers three complementary multi-agent execution paradigms:

The /goal command dynamically plans, decomposes, and orchestrates an entire multi-agent pipeline from all registered characters:

/goal Build a complete REST API in Express, write unit tests, and audit security vulnerabilities.

1. Intelligent Planning: The orchestrator inspects available agent craft signatures and builds an execution DAG with dependency ordering and optional PARALLELO blocks.
2. Sequential & Staged Execution: Each assigned agent performs their turn, inspecting workspace files generated by preceding agents.
3. Supervisor Verification: The overseer validates outputs. If criteria are unmet, the failed step is routed for automated rework.
4. Per-Agent Telemetry Summary: Displays a clean token and timing breakdown:

📊 AGENT PERFORMANCE SUMMARY
  Agent              Out tok    Ctx tok   Tot tok    Time     Speed
  Geordi (Dev)          1420      12400     13820    14.2s   100.0 tok/s
  Worf (Security)        890      14500     15390     8.1s   109.8 tok/s
  Pike (Supervisor)      340      15800     16140     3.4s   100.0 tok/s
  ----------------------------------------------------------------------
  TOTAL                 2650      15800     45350    25.7s   103.1 tok/s

Run pre-configured multi-agent teams (teams/*.json) designed for specific domains:

/team cyber_audit "Harden SSH configuration and scan repository for leaked secrets"

Initiate structured round-table debates across multiple agents on any question:

/call @tuvok, @deanna_troi, @geordi "Should we migrate the backend from REST to GraphQL?"

• Protocol Resolution: Status is negotiated deterministically via tool_call (report_status, route_next, cast_vote) $\to$ regex text fallback $\to$ safety default. Degradations are visibly logged.
• Run Blackboard (blackboard.ts): An ephemeral scratchpad isolated per workflow via AsyncLocalStorage. Agents exchange structured notes (post_note, read_notes) without cluttering main chat context.

To prevent models from hallucinating false success, TSUKA enforces objective verification gates:

graph TD
    A[Agent Action] --> B{Objective Criteria?}
    B -- Yes --> C[Run Shell / File / JSON Check]
    B -- No --> D{Designated Verifier?}
    C -- Failed --> E[Inject Concrete Error Report]
    C -- Passed --> F[Complete Step]
    D -- Rejected --> E
    D -- Approved --> F
    E --> G{Anti-Stall Check}
    G -- Identical Hash --> H[Halt with no_progress]
    G -- New Progress --> I[Retry with Remaining Budget]

1. Objective Acceptance: Configured command execution exit code (0), file existence check, or JSON validity.
2. Third-Party Verifier: Peer agent review via cast_vote or report_status.
3. Anti-Stall Detection: Hashes output and modified files to stop execution early if an agent loops on identical failed attempts.

Every tool is implemented in pure TypeScript (src/tools/impl/*.ts) with an OpenAI-compatible JSON schema (tools_schemas/*.json).

Capable models (MEDIUM / LARGE tier) can create and register custom tools on the fly:

// Example tool created autonomously by an agent:
create_tool({
  name: "count_lines",
  description: "Counts total lines in a target file",
  riskLevel: "SAFE",
  parameters: {
    type: "object",
    properties: { path: { type: "string" } },
    required: ["path"]
  },
  executeBody: "const content = require('fs').readFileSync(args.path, 'utf-8'); return 'Total lines: ' + content.split('\\n').length;"
})

• Sandbox Validation: Code is pre-scanned and evaluated inside a restricted node:vm sandbox.
• Safety Backups: Existing tools are automatically backed up to tools_backup/ before replacement.

TSUKA operates on a defense-in-depth safety architecture:

[ Incoming Tool Request ]
          │
          ├── SAFE Tools ──────────────► Executed immediately
          │
          ├── RESTRICTED Tools ────────► Interactive [y/N/always] prompt per session
          │
          └── DANGEROUS Tools ─────────► MANDATORY [y/N] prompt (never bypassable)

• Workspace Jail: Restricts file reads/writes strictly within workspaceRoot via resolveSafePath(). Escaping via .. or symbolic links is blocked.
• Serialized Prompt Queue: Concurrent parallel agents queue security prompts cleanly without terminal collision.
• Credential Masking: Automatically strips sensitive environment variables (API_KEY, SECRET, PASSWORD, TOKEN) from all logs and prompts.

Rather than relying on model name heuristics, TSUKA includes an empirical capability benchmark:

/benchmark           # Benchmark the active LLM model
/benchmark all       # Benchmark all models on the connected server

• Objective Test Sets: Runs 5 standardized test suites in benchmarks/ measuring instruction following, JSON schema compliance, multi-step tool calls, and distractor tolerance.
• Dynamic Tier Gating:
  • SMALL: Standard tools (21 tools). Dangerous and complex escalation tools are withheld.
  • MEDIUM / LARGE: Full toolset (27 tools), unlocks create_tool, spawn_agent, and shell execution.

TSUKA employs an orthogonal separation of persona, capabilities, and execution:

$$\text{Character (Agent)} = \text{Role (Capabilities & Tools)} \times \text{Trait (Personality & Tone)}$$

┌───────────────────────────────────────────────────────────────────┐
│                           TSUKA CORE                              │
│                                                                   │
│   CLI REPL (src/cli/)  ◄───►  TUI Dashboard (src/tui/)            │
│            │                               │                      │
│            └───────────────┬───────────────┘                      │
│                            ▼                                      │
│                Agent ReAct Loop (src/core/agent.ts)               │
│                            │                                      │
│         ┌──────────────────┼──────────────────┐                   │
│         ▼                  ▼                  ▼                   │
│   LLM Provider       Tool Registry    Permission Manager          │
│   (OpenAI API)     (Hot Auto-Scan)    (3-Tier Safety)             │
│         │                  │                  │                   │
│         ▼                  ▼                  ▼                   │
│  Ollama / Unsloth    27 Native Tools    Workspace Jail            │
└───────────────────────────────────────────────────────────────────┘

harness/
├── src/
│   ├── cli/             # CLI REPL loop, prompt streaming, commands
│   ├── tui/             # Full-screen TUI (double-buffered screen, store, widgets)
│   ├── core/            # ReAct engine, LLM provider, memory, context budgeter
│   ├── tools/           # Dynamic tool registry & 27 native implementations
│   └── safety/          # Permission manager, workspace jail, prompt queue
├── characters/          # 24 Character definitions (roles + trait bindings)
├── roles/               # 21 Operational roles (system prompts + allowed tools)
├── traits/              # 9 Behavioral traits (tone, style, guidelines)
├── teams/               # 10 Preconfigured team configurations
├── benchmarks/          # 5 Declarative JSON benchmark suites
├── tools_schemas/       # 27 JSON schemas for tool validation
└── tests/               # 65 automated test suites

TSUKA includes a comprehensive suite of 65 automated test suites with 1,200+ assertions:

# Run the complete test suite
npm test

# Run individual test suites
npx tsx tests/test_roles.ts
npx tsx tests/test_memory.ts
npx tsx tests/test_fingerprinting.ts
npx tsx tests/test_self_authoring.ts
npx tsx tests/test_goal_orchestrator.ts

Explore our in-depth guides in the docs/ directory:

The GitHub Wiki is automatically compiled from these documentation files via npm run wiki:build.

• Full-Screen Zero-Flicker Interactive TUI (v0.5.1).
• Measured inference telemetry with live prefill/decode tracking.
• Empirical capability fingerprinting and JSON benchmarks.
• Direct streaming for sandboxed custom tools.
• Web-based visualization portal & agent trace graph inspector.
• Extended LSP (Language Server Protocol) tool integration.

Contributions and pull requests are welcome!

1. Adding Tools: Create src/tools/impl/<tool>.ts and tools_schemas/<tool>.json.
2. Adding Personas: Create plain JSON files in characters/, roles/, traits/, or teams/.
3. Running Tests: Ensure all 65 test suites pass cleanly (npm test).

This project is licensed under the MIT License — free for educational, personal, and commercial use.