README
¶
TTal
Hi, I'm TTal — yes, a snail. Slow to break things, fast to ship them.
I carry my whole house in one binary — no cloud, no containers, no dependencies sprawl. Drop me in your terminal and I'll route tasks to the right agent, spawn workers in parallel, and leave a trail of merged PRs behind me.
Agent ops CLI. One binary. Your terminal is the factory floor.
What it does
TTal turns your terminal into an agent assembly line. You describe what needs to happen, TTal handles the rest:
- Route tasks to the right agent — researcher investigates, designer plans, worker implements
- Spawn workers in isolated git worktrees — parallel execution, zero conflicts
- Ship PRs with automated review — 6 review agents, squash-merge from your phone
- Talk to your agents from Telegram — they talk back
task created → research → design → worker spawns → PR opens → review → merge → cleanup
All automatic. All in your terminal.
See it work
# Create a task
ttal task add --project myapp "Add JWT authentication to the API"
# Advance — routes to researcher, designer, or spawns worker based on pipeline stage
ttal go abc12345
# Meanwhile, you're on your phone
# Review agents post verdicts, worker triages feedback, you merge from Telegram
We built TTal with TTal. 356 PRs merged, 29k lines of Go in 33 days. Then we pointed it at flicknote-cli — 55 PRs merged in 15 days, Rust. Same pipeline, different repo, same velocity.
Architecture
TTal is three things:
┌─────────────────────────────────────────┐
│ TTal the orchestrator │
│ routes tasks, spawns │
│ workers, manages agents │
├─────────────────────────────────────────┤
│ logos the reasoning engine │
│ bash-only agent loop │
│ LLMs think in plain text │
├─────────────────────────────────────────┤
│ temenos the sacred boundary │
│ seatbelt (macOS) / bwrap │
│ (Linux) — YAGNI containers│
└─────────────────────────────────────────┘
TTal coordinates. logos thinks. temenos isolates. Workers can't touch each other or the host.
Logos is a bash-only reasoning engine — no tool schemas, no JSON ceremony. Temenos is OS-native filesystem isolation — no containers needed. Three repos, one pipeline.
Install
brew tap tta-lab/ttal
brew install ttal
Or from source:
go install github.com/tta-lab/ttal-cli@latest
Quick start
Clone the repo and run /setup in Claude Code:
git clone https://github.com/tta-lab/ttal-cli.git && cd ttal-cli
# Open in Claude Code, then: /setup
The setup skill installs TTal, configures hooks, and walks you through Telegram integration. Five minutes to your first automated PR.
Or do it manually:
ttal doctor --fix # install hooks
ttal daemon install # start the communication hub
The team
TTal agents aren't chatbots. They're specialists with clear roles:
| Agent | Role | What they do |
|---|---|---|
| Yuki 🐱 | Orchestrator | Routes tasks, manages the pipeline |
| Athena 🦉 | Researcher | Investigates problems, writes findings |
| Inke 🐙 | Designer | Reads research, writes implementation plans |
| Workers | Coders | Spawn per-task, implement, open PRs, self-cleanup |
Each agent runs in its own tmux session. Workers get isolated git worktrees — they can't step on each other. The daemon handles all messaging: Telegram in, agent-to-agent routing, status updates out.
How it connects
TTal is the execution layer of the GuionAI ecosystem:
- FlickNote captures knowledge — voice memos, links, meeting notes
- TTal agents read and write to FlickNote via CLI — plans, research findings, even agent definitions live there
No MCP. CLI-first. Agents use the same tools you do.
License
MIT
Documentation
¶
There is no documentation for this package.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
gen-schema
command
|
|
|
internal
|
|
|
agentfs
Package agentfs discovers and reads agent metadata from the filesystem.
|
Package agentfs discovers and reads agent metadata from the filesystem. |
|
ask
Package ask provides the core ask agent loop and supporting types.
|
Package ask provides the core ask agent loop and supporting types. |
|
breathe
Package breathe handles session handoff for context window refresh.
|
Package breathe handles session handoff for context window refresh. |
|
claudeconfig
Package claudeconfig manages Claude Code configuration files (~/.claude.json).
|
Package claudeconfig manages Claude Code configuration files (~/.claude.json). |
|
comment
Package comment provides comment storage via ent.
|
Package comment provides comment storage via ent. |
|
config
Package config loads and resolves the ttal configuration from ~/.config/ttal/config.toml.
|
Package config loads and resolves the ttal configuration from ~/.config/ttal/config.toml. |
|
daemon
Package daemon implements the long-running ttal manager-plane process.
|
Package daemon implements the long-running ttal manager-plane process. |
|
dictate
Package dictate implements a push-to-talk voice dictation daemon for macOS.
|
Package dictate implements a push-to-talk voice dictation daemon for macOS. |
|
doctor
Package doctor runs diagnostic checks on the ttal installation and configuration.
|
Package doctor runs diagnostic checks on the ttal installation and configuration. |
|
enrichment
Package enrichment derives metadata from task descriptions.
|
Package enrichment derives metadata from task descriptions. |
|
env
Package env provides environment variable helpers for spawning subprocesses.
|
Package env provides environment variable helpers for spawning subprocesses. |
|
format
Package format provides shared display helpers for CLI output.
|
Package format provides shared display helpers for CLI output. |
|
frontend
Package frontend abstracts messaging transport (Telegram, Matrix) behind a unified interface.
|
Package frontend abstracts messaging transport (Telegram, Matrix) behind a unified interface. |
|
git
Package git provides low-level git repository helpers.
|
Package git provides low-level git repository helpers. |
|
gitprovider
Package gitprovider offers a provider-agnostic interface for git hosting operations.
|
Package gitprovider offers a provider-agnostic interface for git hosting operations. |
|
gitutil
Package gitutil manages git worktree lifecycle for worker sessions.
|
Package gitutil manages git worktree lifecycle for worker sessions. |
|
launchcmd
Package launchcmd builds the shell command used to launch a worker or reviewer session.
|
Package launchcmd builds the shell command used to launch a worker or reviewer session. |
|
license
Package license implements tiered licensing for TTAL using Ed25519-signed JWTs.
|
Package license implements tiered licensing for TTAL using Ed25519-signed JWTs. |
|
message
Package message provides CRUD operations for persisting daemon messages.
|
Package message provides CRUD operations for persisting daemon messages. |
|
notify
Package notify provides fire-and-forget Telegram notifications for the active team.
|
Package notify provides fire-and-forget Telegram notifications for the active team. |
|
onboard
Package onboard implements the guided first-run setup flow for ttal.
|
Package onboard implements the guided first-run setup flow for ttal. |
|
open
Package open provides commands to open a task's context in various ways.
|
Package open provides commands to open a task's context in various ways. |
|
pipeline
Package pipeline implements the pipeline stage engine for task workflow orchestration.
|
Package pipeline implements the pipeline stage engine for task workflow orchestration. |
|
planreview
Package planreview spawns and manages plan-review sessions in tmux windows.
|
Package planreview spawns and manages plan-review sessions in tmux windows. |
|
pr
Package pr implements pull request operations for worker sessions.
|
Package pr implements pull request operations for worker sessions. |
|
project
Package project manages the TOML-backed project registry for ttal.
|
Package project manages the TOML-backed project registry for ttal. |
|
review
Package review manages reviewer session lifecycle for PR review.
|
Package review manages reviewer session lifecycle for PR review. |
|
route
Package route handles file-staged routing requests for agent breathe-on-route.
|
Package route handles file-staged routing requests for agent breathe-on-route. |
|
runtime
Package runtime defines the coding agent runtime abstraction layer.
|
Package runtime defines the coding agent runtime abstraction layer. |
|
scaffold
Package scaffold applies workspace templates to bootstrap new agent workspaces.
|
Package scaffold applies workspace templates to bootstrap new agent workspaces. |
|
skill
Package skill provides a runtime-agnostic skill registry backed by flicknote.
|
Package skill provides a runtime-agnostic skill registry backed by flicknote. |
|
status
Package status reads and writes live agent session status files.
|
Package status reads and writes live agent session status files. |
|
sync
Package sync deploys skills, subagent definitions, and config TOMLs to runtime directories.
|
Package sync deploys skills, subagent definitions, and config TOMLs to runtime directories. |
|
taskwarrior
Package taskwarrior provides shared helpers for interacting with taskwarrior.
|
Package taskwarrior provides shared helpers for interacting with taskwarrior. |
|
team
Package team provides team-scoped agent session management.
|
Package team provides team-scoped agent session management. |
|
telegram
Package telegram provides Telegram Bot API helpers for sending messages and managing interactions.
|
Package telegram provides Telegram Bot API helpers for sending messages and managing interactions. |
|
tmux
Package tmux provides helpers for managing tmux sessions, windows, and input delivery.
|
Package tmux provides helpers for managing tmux sessions, windows, and input delivery. |
|
today
Package today manages the daily focus task list via taskwarrior scheduled dates.
|
Package today manages the daily focus task list via taskwarrior scheduled dates. |
|
tui
Package tui provides the interactive terminal UI for browsing and managing tasks.
|
Package tui provides the interactive terminal UI for browsing and managing tasks. |
|
usage
Package usage logs ttal command invocations to SQLite for auto-compact summaries.
|
Package usage logs ttal command invocations to SQLite for auto-compact summaries. |
|
voice
Package voice provides text-to-speech generation via a local Kokoro-compatible server.
|
Package voice provides text-to-speech generation via a local Kokoro-compatible server. |
|
watcher
Package watcher tails Claude Code JSONL session files and forwards agent output to Telegram.
|
Package watcher tails Claude Code JSONL session files and forwards agent output to Telegram. |
|
worker
Package worker manages the full lifecycle of spawned worker sessions.
|
Package worker manages the full lifecycle of spawned worker sessions. |
|
tools
|
|
|
keygen
command
ttal-keygen generates Ed25519 keypairs and signs license JWTs for TTAL.
|
ttal-keygen generates Ed25519 keypairs and signs license JWTs for TTAL. |
Click to show internal directories.
Click to hide internal directories.