TaskForceAI TUI Client

This directory contains a Bubble Tea client that talks to the live TaskForceAI multi-agent orchestrator API. It mirrors the operator dashboard in a terminal-first workflow: keyboard navigation, streaming agent progress, tool telemetry, and a bottom-docked chat input that submits prompts directly to the orchestrator.

Architecture & Tech Stack

• Runtime & UI
  • Go 1.25.6, compiled to a single static binary.
  • Bubble Tea drives the state machine, while Bubbles + Lipgloss render the run list, detail pane, and chat dock.
  • The app entrypoint (main.go → internal/app → internal/app/cli → internal/app/cli/models) isolates terminal UI logic from configuration, persistence, and API layers so tests can exercise each piece independently.
• Networking
  • internal/app/api wraps TaskForceAI’s HTTP+SSE endpoints with typed structs, streaming readers, and context-aware retries. Long-lived streams run on their own goroutines and push updates into Bubble Tea messages.
  • Device login and auto-update flows live in the same package so authentication and binary swaps stay encapsulated.
• Persistence & Offline Workflow
  • Session state persists to both history.json and a SQLite database (internal/app/persistence). SQLC-generated code wraps every query so schema drift is caught at compile time.
  • The persistence layer exposes helpers for run hydration, snapshots, pending prompt queues, and local search. During startup the model loads history from disk, merges it with SQLite, and opens any pending retries.
• Observability
  • Structured logging uses log/slog with level + format controls exposed through /config logging.
  • internal/app/observability wires Sentry; telemetry can be toggled or pointed to custom DSNs/environments at runtime.
• Dev Experience
  • Watcher-based dev loop (bun run cli:dev) rebuilds and respawns the TUI on source changes.
  • Tests cover CLI state transitions, persistence edge cases, and API contracts (go test ./...; see “Testing” below).
  • Auto-update logic uses go-github-selfupdate to download signed releases and swap binaries in place.

Prerequisites

• Go 1.23 or newer (brew install go on macOS, apt install golang on Debian/Ubuntu, etc.)
• A TaskForceAI account with access to the /api/v1 endpoints

Install It

macOS, Linux, WSL (curl)

curl -fsSL https://taskforceai.chat/install.sh | bash

This downloads a prebuilt binary for your platform and installs it to ~/.local/bin. Override the install location with TASKFORCEAI_INSTALL_DIR:

curl -fsSL https://taskforceai.chat/install.sh | TASKFORCEAI_INSTALL_DIR=/usr/local/bin bash

Native installs automatically update in the background. Set TASKFORCEAI_DISABLE_AUTOUPDATE=1 to opt out.

Homebrew

brew install ClayWarren/taskforceai/taskforceai-cli

Windows PowerShell

irm https://taskforceai.chat/install.ps1 | iex

Windows CMD

curl -fsSL https://taskforceai.chat/install.cmd -o install.cmd && install.cmd && del install.cmd

Manual Download

Download the latest release for your platform from GitHub Releases, extract it, and add the binary to your PATH.

Run It

cd apps/tui
go run .

Dev Loop (Auto Reload)

bun run cli:dev

This runs the bundled watcher (cmd/dev) so the TUI rebuilds and restarts whenever Go sources, templates, or config files change.

Prefer a manual launch? You can call the watcher directly:

cd apps/tui
go run ./cmd/dev

The client stores configuration under ~/.config/taskforceai/ (override with $TASKFORCEAI_CONFIG_DIR).

Controls & Commands

• Tab toggles focus between the run list and the chat bar.
• Up/Down (or k/j) move through runs and refresh the detail pane.
• PgUp/PgDn or mouse wheel scroll through chat history when chat is focused.
• Enter sends whatever is in the chat input.
• ctrl+d deletes the currently selected run from local history.
• q or ctrl+c exits.

Slash commands:

• /login – open your browser to authenticate with TaskForceAI (device login flow).
• /logout – clear the cached token.
• /sync – pull the latest conversation history from TaskForceAI.
• /clear, /reset, /new – wipe the current session state and start fresh.
• /search <query> – fuzzy search across local prompts, outputs, and logs.
• /model [list|set <id>|reset] – choose which AI model powers new prompts.
• /config theme <light|dark|system> – switch the accent palette for the terminal UI.
• /config telemetry <on|off|dsn|env> – control crash-reporting (Sentry) and its DSN/environment.
• /config logging <level|format> – set the structured log level (debug|info|warn|error) and format (text|json).
• /mock – toggle a local mock API server for SDK development (runs on localhost:4321).
• /help – list available commands and what they do.
• /usage – show run usage stats from the local history.
• /mcp – manage MCP servers and list configured tools (see below).
• /exit, /quit – close the terminal client.

Headless Mock Server

Run the mock API server without the TUI for scripting and testing:

taskforceai --mock

This starts the server at http://localhost:4321/api/developer and blocks until Ctrl+C. Useful for SDK integration testing.

Anything else you type is posted to /api/v1/run; progress streams in from /api/v1/stream/<taskId>, and completed runs persist locally (history.json) so the dashboard survives restarts.

Output

• Run list (left) – newest runs first, coloured by status.
• Run detail (right) – prompt, agent statuses, tool usage, logs, and synthesized output.
• Chat dock (bottom) – threaded messages with live-updating OpsBot responses as the stream unfolds.
• Theming – colors match the TaskForceAI dark theme palette so terminal and web console feel consistent.

Telemetry & Logging

• Telemetry (Sentry) is disabled by default. Provide a DSN via /config telemetry dsn <value> or the TASKFORCEAI_SENTRY_DSN env var, then run /config telemetry on to start capturing crashes. /config telemetry env <name> sets the environment tag (defaults to cli).
• Structured logging flows through log/slog. Use /config logging format json when piping logs into other tools, and /config logging level debug for verbose diagnostics. Defaults are info level and human-friendly text output.
• All settings persist in ~/.config/taskforceai/config.json (or $TASKFORCEAI_CONFIG_DIR). Toggle them back with /config telemetry off and /config logging level info.

Local Persistence & sqlc

• The TUI caches prompts, outputs, tool traces, and queued retries inside a local SQLite database (~/.config/taskforceai/taskforceai.db). The normalized schema lives in internal/app/persistence/schema.sql; the same file is embedded at runtime and feeds sqlc so schema drift is impossible.
• All queries are defined under sqlc/queries/ (grouped by conversations, messages, and pending prompts). sqlc turns those statements into strongly-typed Go helpers in internal/app/persistence/sqlc/.
• Editing the schema or queries requires regenerating the bindings: install sqlc (brew install sqlc or go install github.com/sqlc-dev/sqlc/cmd/sqlc@latest), then run sqlc generate from apps/tui. CI will fail to build if the generated file is stale or missing.
• Tests that touch persistence (go test ./internal/app/persistence ./internal/app/cli/models) automatically exercise the generated layer plus migrations, so always re-run them after changing schema/queries.
• Need to run without SQLite? set TASKFORCEAI_DISABLE_SQLITE=1 before launching the CLI to skip local persistence entirely. The UI will inform you that on-disk caching is disabled.

Next Steps

• Publish prebuilt binaries alongside the npm installer for air-gapped environments.
• Stream metrics, traces, and workflow queues alongside agent/tool telemetry.
• Harden release automation with signed artifacts and channel promotion.

Auto Updates

• The TUI checks GitHub releases for claywarren/taskforceai-tui on startup.
• If a newer semantic version exists, it downloads + swaps the binary in-place, then prompts you to restart.
• Set TASKFORCEAI_DISABLE_AUTOUPDATE=1 to skip the check (useful for air-gapped or QA scenarios).
• Set TASKFORCEAI_UPDATE_REPO=owner/repo to pull releases from a different fork/channel.

Code Quality

Run the Go format/lint/build loop from the repo root:

bun run format:cli
bun run lint:cli
bun run typecheck:cli
bun run test:cli

Testing

cd apps/tui
go test ./...
staticcheck ./...

MCP helpers:

• /mcp or /mcp list – show configured servers and their tools.
• /mcp add <name> <endpoint> [tools=tool1,tool2] [enabled=true|false] – register or update a server.
• /mcp remove <name> – delete a server entry.
• /mcp tools <name> <tool1,tool2,...> – replace the tool list for a server.
• /mcp enable <name> / /mcp disable <name> – toggle a server without removing it.