Personal AI agent controllable via Telegram and a Web Admin UI. Built around a ReAct agent loop with FastAPI, SQLite persistence, real token streaming, a multi-agent kanban board, and MCP server support. Works with any OpenAI-compatible model (local via Ollama or cloud).

curl -fsSL https://raw.githubusercontent.com/vakovalskii/LocalTaskClaw/main/install.sh | bash

The interactive wizard walks through mode selection, Telegram bot setup, model choice, and service registration. Takes about 5 minutes.

• Telegram bot with live typing preview (Bot API 9.3+ sendMessageDraft, editMessageText fallback)
• Admin UI (SPA) -- chat, sessions, kanban board, tasks, files, logs, settings
• Kanban board -- 5-column board (Backlog / In Progress / Review / Done / Needs Human), up to 10 agents with custom identities and roles
• Orchestrator / Worker model -- orchestrator agents dispatch workers via kanban_run, read artifacts via kanban_read_result, verify via kanban_verify, send reports via kanban_report
• Auto-retry -- rejected tasks retry up to 2 times, then escalate to Needs Human
• Repeat / heartbeat -- tasks with repeat_minutes > 0 auto-rerun on schedule
• Parallel tool calls -- agents run multiple tools concurrently via asyncio.gather
• Real token streaming -- SSE streaming in both Admin UI and Telegram
• Web search via DuckDuckGo (Brave API optional)
• MCP servers -- extend the agent with any Model Context Protocol tool
• Skills system -- SKILL.md scanner + npx skills add ecosystem
• Security -- hard-block (fork bombs, exfil), soft-confirm (rm -rf, DROP TABLE), injection detection
• Any OpenAI-compatible model -- Ollama (local) or cloud API

core/           Python ReAct agent + FastAPI + SQLite
bot/            Telegram bot (single-user, OWNER_ID guard)
frontend/       Admin UI — React + TypeScript + Tailwind CSS (builds to admin/)
admin/          Built SPA output served by Core at /admin
scripts/        Utilities (seed_kanban.py)
tests/          End-to-end integration tests
ltc             Unified CLI for all operations

The Core listens on port 11387 by default. The Bot connects to Core over HTTP. The Admin UI is served by Core at /admin.

The installer offers three isolation levels:

Agent runs inside containers (multi-stage build: Node.js builds the React frontend, Python runs the core). Access is limited to a dedicated volume. Requires Docker, Docker Compose, and git.

Agent runs as a Python process directly on the host. Full filesystem access. Requires Python 3.12+, git, pip.

Same as native, but the agent is confined to ~/.localtaskclaw/workspace. File tools cannot escape the workspace directory.

The installer places ltc in ~/bin/ltc. All operations go through this single command.

ltc start              Start services (core + bot)
ltc stop               Stop services
ltc restart            Restart services
ltc status             Show status, port, model
ltc logs [core|bot]    Tail logs (default: core)
ltc test [target]      Run tests (all | kanban | seed) [--keep]
ltc seed [--reset]     Seed demo kanban board
ltc update             Pull latest code & restart
ltc build              Rebuild frontend (React → admin/)
ltc open               Open admin UI in browser
ltc uninstall          Remove LocalTaskClaw completely
ltc help               Show help

curl -fsSL https://raw.githubusercontent.com/vakovalskii/LocalTaskClaw/main/install.sh | bash

The wizard prompts for:

• Installation mode (Docker / Native / Restricted)
• Telegram bot token (validated live against the Bot API)
• Owner Telegram ID (auto-detected via /start or entered manually)
• LLM provider (Ollama with hardware-aware model picker, or external OpenAI-compatible API)

After completion it registers system services, performs a health check, and installs the ltc CLI.

ltc update

Pulls the latest code via git, reinstalls dependencies if requirements.txt changed, rebuilds the frontend, and restarts services. Supports --quiet flag for headless execution (called from API).

ltc uninstall

Stops services, removes LaunchAgents/systemd units, deletes ~/.localtaskclaw (code, venv, database, secrets, workspace), removes ~/bin/ltc, and cleans up log files. Prompts for confirmation before proceeding.

Seed the board with 4 specialist worker agents, 1 orchestrator, and 5 demo tasks:

ltc seed

Reset all existing data and re-seed from scratch:

ltc seed --reset

Print current board state without changes:

ltc seed --status

Integration tests run against the live service at localhost:11387.

Run all tests:

ltc test

Kanban team-run e2e test (spawns agents, orchestrator dispatches workers, produces artifacts):

ltc test kanban

Seed pipeline validation:

ltc test seed

Use --keep to preserve test data after the run (useful for inspecting results in the UI):

ltc test kanban --keep

ltc build

Installs npm dependencies and builds the React + Tailwind SPA into admin/.

The ltc CLI auto-detects the platform and uses the appropriate service manager:

ltc start       # Start core + bot
ltc stop        # Stop all services
ltc restart     # Stop then start
ltc status      # Show running state, port, model version
ltc logs        # Tail core logs (or: ltc logs bot)

• URL: http://localhost:11387/admin
• Login: use the API_SECRET value from secrets/core.env as password

Pages:

Messages sent through the Admin UI are also forwarded to the owner's Telegram chat.

All endpoints require the X-Api-Key header set to API_SECRET (except /health).

Environment variables are stored in secrets/core.env (native/restricted) or passed via Docker environment.

Configure external MCP tool servers in workspace/mcp_servers.json:

{
  "servers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "ghp_..." }
    }
  }
}

MCP tools are auto-discovered and appear as mcp_{server}_{tool_name} in the agent's tool list. The agent communicates with MCP servers via stdio JSON-RPC 2.0 transport.

MIT