What is Kosmos?

Kosmos is a local-first orchestration hub for software work. It combines a lightweight Kanban workflow, REST API, real-time WebSocket events, and an embedded dashboard so you can coordinate projects and tasks from one place.

Platform Walkthrough

1) Dashboard overview

Main landing page with project cards, summary stats, global search, and quick actions.

2) Kanban board by workflow stage

Project board split into todo, progress, qa, and done columns. Tasks can be dragged between columns to trigger workflow transitions.

3) Task detail modal

Detailed task view used to inspect title, state, ownership, priority, and execution context.

4) Live activity panel

Real-time feed powered by WebSocket events to monitor platform activity while tasks move through the workflow.

Architecture At A Glance

Release Roadmap

Features

• REST API for projects, tasks, transitions, comments, artifacts, settings, metrics, and workflow cycle
• WebSocket broadcast channel for real-time dashboard updates
• Embedded frontend served by the same process
• Deterministic Kanban cycle (todo -> progress -> qa -> done)
• Optional LLM-backed agent chat endpoint (disabled by default)
• Dynamic subagent discovery from profile directories

Tech Stack

Quick Start

Option 1: Script (recommended)

./start.sh

Option 2: Manual

python -m src.backend --host 0.0.0.0 --port 18794

Option 3: Installed CLI

battlestation --host 0.0.0.0 --port 18794

The CLI command remains battlestation for compatibility during the branding migration.

Open dashboard:

http://localhost:18794/

Build frontend bundle (if needed):

npm run build --prefix src/frontend

Security environment variables

• KOSMOS_CORS_ALLOWED_ORIGINS: comma-separated CORS allowlist (default *)
  • Example: KOSMOS_CORS_ALLOWED_ORIGINS=http://localhost:3000,https://dashboard.example.com
• KOSMOS_API_TOKEN: when set, all /api/* routes require authentication
  • Allowed headers: Authorization: Bearer <token>, X-Kosmos-Token: <token>, or legacy X-Battlestation-Token: <token>
  • /health and /ws remain public
• KOSMOS_ENABLE_AGENT_CHAT: controls /api/agents/{id}/chat endpoint (default false)
  • Set to true only if you intentionally want LLM-backed chat calls
• OLLAMA_VERIFY_TLS: enable/disable TLS verification for Ollama HTTP calls (default true)
  • Accepted values: true|false|1|0|yes|no

Data paths

• Main DB default: ~/.kosmos/kosmos.db (falls back to legacy ~/.battlestation/battlestation.db if present)
• Artifact storage default: ~/.kosmos/artifacts/ (falls back to legacy ~/.battlestation/artifacts/ if present)

API and WebSocket

• REST: http://localhost:18794/api
• Health: http://localhost:18794/health
• WebSocket: ws://localhost:18795 and ws://localhost:18794/ws

Project layout

.
├── src/
│   ├── agents/
│   │   ├── agent.py
│   │   ├── personalities.py
│   │   ├── subagents/
│   │   │   ├── base.py
│   │   │   └── factory.py
│   │   └── profiles/
│   │       ├── kosmos/
│   │       ├── vicks/
│   │       └── wedge/
│   ├── backend/
│   │   ├── api.py
│   │   ├── database.py
│   │   ├── server.py
│   │   ├── workflow.py
│   │   └── __main__.py
│   ├── frontend/
│   │   ├── src/
│   │   └── dist/
│   └── __init__.py
├── tests/
├── pyproject.toml
└── start.sh

Development

python3 -m venv .venv
.venv/bin/python -m pip install -e .[test]
.venv/bin/pytest

Agent Profiles

Agent behavior is externalized under src/agents/profiles/.

• One folder per agent id (dynamic discovery)
• kosmos is the orchestrator id
• Any other profile folder becomes a valid subagent id automatically
• Core docs per agent: PROFILE.md, SOUL.md, WORKFLOW.md, STYLE.md, GUARDRAILS.md, MEMORY.md
• PROFILE.md front matter can override: name, role, description, model, temperature, top_p, max_tokens
• Prompt assembly order: PROFILE body -> SOUL -> WORKFLOW -> STYLE -> GUARDRAILS -> MEMORY -> extra *.md files alphabetically

Agent Roles

Agent	Role	Description
Kosmos	Orchestrator	The strategic leader. Receives tasks, breaks them down, delegates to subagents (Vicks/Wedge/any), monitors progress, and coordinates the workflow. It does not write code directly—its job is to orchestrate.
Vicks	Developer	The pragmatic implementer. Writes, fixes, and refactors code. Takes tasks from Kosmos, executes the work, commits changes, and moves tasks to QA when done.
Wedge	QA Engineer	The quality gatekeeper. Reviews code from Vicks, runs tests, validates requirements, and either approves (with qa approved comment) or rejects back to Vicks (with structured qa_rejection payload).

How they work together:

• Kosmos creates tasks and assigns them to Vicks.
• Vicks implements the feature, writes tests, and transitions to qa.
• Wedge validates in QA. If something is missing, sends the task back to progress with rejection context.
• Once Wedge approves, a human reviewer does final approve_qa, and Kosmos closes the task to done.

Verification

npm run build --prefix src/frontend
.venv/bin/pytest -q
.venv/bin/pytest --cov --cov-report=term

License

MIT