kaits

The RPG for your AI agent team.

---

Visual Preview — screenshot coming soon.

Key Features

• Dashboard-first design — living company overview with real-time KPI cards (active agents, tasks, completions, system health), a toggleable task flow pipeline view and virtual office floor plan, activity feed, and heartbeat status panel
• RPG-style progression — agents have roles, skills, levels, and XP that grow through task completion; level-gated borders, party status bar, and promotion toasts
• Conversational agents — chat with any agent in real time, with streamed responses and browser-based voice (STT/TTS)
• YAML-defined agents — version-controllable agent definitions with role, skills, model, and autonomy settings
• Department and org chart — agents belong to departments (engineering, qa, product, etc.) with reports_to chains; department routing assigns tasks to the right team automatically
• Budget and economics — token cost tracking per agent and project, configurable budget caps per scope/period, daily trend aggregation, and alert thresholds; cost data stored in the event log using json_extract
• Process templates — 3 built-in workflow templates (feature development, bug fix, research spike) that generate child task chains with handoff notes and review gates; custom templates loaded from YAML
• Company profile — organization name, mission, and department list injected into every agent's system prompt for organizational context; managed from the Settings page and stored in company.yaml
• Multi-model support — designed for Claude, OpenAI, and self-hosted models (vLLM, Ollama)
• Configurable autonomy — supervised, guided, or autonomous modes per agent and task
• Hierarchical tasks — directory-tree task structure with parent/child decomposition, source/target tracking, human-review flags, and lifecycle hooks
• Event log — append-only SQLite event store driving the activity feed, materializer sync, and heartbeat scheduling
• Lifecycle hooks and triggers — YAML-defined trigger→action chains that run mandatory steps on events (release, task completion, deployment) bypassing agent discretion
• Settings page — configuration UI for company profile, model defaults, token prices, budget caps, API key validation, and logging

Routes

Route	Page
/	Dashboard — KPIs, task flow / office view, activity feed
/chat	Chat — streaming agent conversation with voice
/tasks	Tasks — unified task panel with filters and event timeline
/skills	Skills — role-based skill tree visualization
/projects	Projects — project overview with lifecycle and repo links
/settings	Settings — company profile, model, budget, and logging config

Getting Started

Prerequisites

• Python 3.13+
• uv (recommended) or pip
• An Anthropic API key

Installation

# Clone the repository
git clone https://github.com/projectious-work/kaits.git
cd kaits

# Install dependencies
uv sync

# Set your API key
echo 'ANTHROPIC_API_KEY=your-key-here' > .env

# Initialize and run
uv run reflex init
uv run reflex run

Open http://localhost:3000 in your browser. The dashboard loads with KPI cards, a task flow pipeline, and the agent sidebar.

Dev Container

This project includes a dev container configuration. Open in VS Code with the Dev Containers extension, or use any compatible tool.

Usage

Dashboard

The home page (/) shows the living company overview: real-time KPI cards, a toggleable main view (task flow pipeline or virtual office floor plan), an activity feed, and a heartbeat/budget sidebar. Use the toggle buttons to switch between Task Flow (kanban-style pipeline) and Office View (SVG floor plan with agent avatars placed by department).

Chat with an agent

Navigate to /chat. Click any agent card in the sidebar to start a conversation. Each agent has its own role, personality, and conversation history.

Agent definitions

Agents are defined in agents/*.yaml. Example:

name: researcher
role: Researcher
level: junior
xp: 0
goal: Find, analyse, and synthesise information on any given topic.
department: research
skills:
  - web_research
  - analysis
model:
  provider: anthropic
  model: claude-haiku-4-5-20251001
autonomy: guided

YAML files are seed data — they populate an empty database at startup. After that the database is the source of truth. Use the character creator or Settings to make live changes.

Company profile

Edit company.yaml or use the Settings page (/settings) to set your organization name, mission, and department list. This context is injected into every agent's system prompt automatically.

Process templates

Place YAML process template files in process_templates/. Each template defines a category, steps, and target roles. Apply a template to a parent task to auto-generate a child task chain with the correct handoff notes and review gates.

Configuration

Environment Variable	Description	Default
ANTHROPIC_API_KEY	Anthropic API key for Claude models	(required)
OPENAI_API_KEY	OpenAI API key	(optional)
KAITS_DB_PATH	SQLite database path	kaits.db
LOG_LEVEL	Logging verbosity	INFO
LOG_FILE_ENABLED	Enable JSON log file under logs/	``
DEFAULT_MODEL_PROVIDER	Default model provider	anthropic
DEFAULT_MODEL_NAME	Default model name	claude-haiku-4-5-20251001
TOKEN_PRICES_JSON	Custom token price overrides (JSON)	``
BUDGET_ALERT_PCT	Default budget alert threshold %	80

See rxconfig.py for Reflex-specific settings.

Testing

# Run all tests
uv run poe test

# Run with coverage
uv run poe check

775 tests, 0 failures.

Documentation

Full documentation: coming soon (MkDocs Material site under docs/).

# Build and serve docs locally
uv run mkdocs serve

Contributing

Contributions are welcome. See the Contributing Guide for details.

License

MIT — see LICENSE for details.

---

Built by projectious.work — an AI-native IT consultancy.