Autonomous Business Operating System for Solo Founders

Give Kompany a directive and a budget. The CEO agent conducts the team, delegates tasks, creates revenue projects when funds are short, and never downgrades your mission. Every AI cost is tracked as a real business expense. Works standalone via CLI, REST API, MCP, or SDK.

Open-core. This repo is the whole engine under AGPL-3.0 — no
crippled "community edition." Free for your own company; a
commercial license applies only if you sell
hosted access to others. Commercial extensions (curated playbooks,
specialist agent souls, business integrations) live in a separate
proprietary package, kompany-pro. Details:
Open Core — Core / Pro / Cloud ·
Why AGPL?

Why This Exists

Solo founders make high-stakes decisions daily across product, engineering, finance, marketing, sales, and operations — often without anyone to challenge their thinking. Single-agent AI tools answer questions in isolation. They don't debate, push back, or synthesize cross-functional perspectives.

Kompany gives you an autonomous C-suite that operates — classifying directives, checking budgets, running multi-agent debates, creating revenue projects, and executing tasks — all while tracking every cent of AI cost as a real business expense.

Core Principles

Mission Integrity — The CEO never downgrades the Master's mission. Budget insufficient? Create a revenue project to earn the funds. "We can't afford it" is not an answer. "Here's how we'll fund it" is.
AI Costs Are Real Costs — Every LLM call is an operational expense tracked in the company ledger. The balance can go negative. This increases the revenue target, never cancels the mission.
Goal Persistence — A negative balance doesn't cancel anything. If the company is -€2 after running agents and needs €4,450 for a Mac Studio, the revenue project target is €4,452.
Real Work, Not Just Words — Project tasks run as real multi-turn execution sessions via the Claude Code CLI, Codex CLI, or opencode — on your own subscription or API key — with per-task budget caps and an approval inbox gating side effects.
Always On — A 24/7 daemon (kompany daemon install, launchd-managed) ticks every 5 minutes: heartbeat, then at most one task advanced per tick under the same budget caps and approval gates. The desktop app attaches to the running daemon — one engine, around the clock. kompany suspend is the brake.

How It Works

Master: "Buy a Mac Studio M4 128GB, budget €50"
  │
  ▼
KompanyEngine.process_directive(raw_input)
  │
  ├─ 1. CEO classifies → ACQUISITION, ~€4500, squad: strategy
  │     (AI cost: ~$0.03 → ledger)
  │
  ├─ 2. CFO.check_budget(4500) → balance: €49.97, shortfall: €4450.03
  │     (mechanical, no LLM cost)
  │
  ├─ 3. MISSION INTEGRITY: CEO creates revenue project
  │     CEO consults CRO+CMO+CTO for revenue paths
  │     (AI cost: ~$0.15 → ledger, balance now ~€49.82)
  │     Revenue target = €4500 - €49.82 = €4450.18
  │     Creates Project with paths + auto-trigger on funded
  │
  └─ 4. Report to Master with plan + running cost summary

The Executive Team

Agent	Role	Type	Optimizes For
CEO	Final decision-maker & conductor	LLM (Opus)	Vision, strategy, mission integrity
CFO	Financial gatekeeper & cost visibility	LLM (Sonnet)	Budget checks, balance tracking, financial monitoring
CTO	Technology leadership	LLM (Sonnet)	Technical correctness, scalability
CPO	Product leadership	LLM (Sonnet)	User value, time-to-market, PMF
CMO	Marketing leadership	LLM (Sonnet)	Brand equity, top-of-funnel growth
CRO	Revenue leadership	LLM (Sonnet)	Pipeline, deal velocity, ARR
COO	Operations leadership	LLM (Sonnet)	Execution capacity, process reliability
CSA	Solution architecture	LLM (Sonnet)	Architectural integrity, integrations
CISO	Security & compliance	LLM (Sonnet)	Risk mitigation, compliance posture
CoS	Debate moderator & synthesizer	LLM (Sonnet)	Neutral facilitation, structured briefs
CV	Brand visuals & visual direction	LLM (Sonnet)	Visual consistency, brand identity

Execution Subagents

Agent	Role
Analyst	Financial modeling & ROI analysis
Builder	Code & product creation
Procurement	Vendor research & negotiation
Researcher	Market research & data gathering
Writer	Content creation & copywriting

Communication

All agents communicate through direct function calls via KompanyEngine. CoS coordinates cross-functional issues and helps CEO make final calls. See docs/context/core-architecture.md for details.

Installation
Quick Start
Usage Guide
Directive Types
Autonomy Tiers
Channels — Telegram, Email, Outbox
Anima — the Company Persona
Self-Update Pipeline
Multi-Agent Debates
Stage Profiles
Multi-Provider LLM Support
Project Structure
Configuration
Running Tests
Open Core — Core / Pro / Cloud
Contributing
Support
License

Quick Start (Desktop App)

Kompany ships as a desktop bundle — double-click, fill out the in-window
onboarding form, and you're live, no Python install or terminal needed.

No prebuilt binaries yet. Pre-built installers are not published to
GitHub Releases at this stage. Build the bundle locally with
./kompany/build_desktop.sh from a checkout — it produces the platform
artifact below. See docs/context/distribution.md
for toolchain prerequisites. (Or skip the desktop app entirely and use
the CLI / source install.)

Platform	Artifact (built locally)	First-launch
macOS	`Kompany.dmg` (drag to Applications)	Right-click the app icon → Open the first time (built app is unsigned).
Windows	`Kompany.msi`	SmartScreen → More info → Run anyway.
Linux	`Kompany.AppImage`	`chmod +x Kompany.AppImage && ./Kompany.AppImage`

On first launch a cyberpunk onboarding wizard walks you through six
steps in the same window:

Connection — pick a provider, paste your API key (custom
OpenAI-compatible endpoints supported; auto-filled from env / a
data-dir .env when present). The key is verified by a live ping
and stashed to the encrypted vault immediately, so quitting
mid-flow never loses it.
Faction — choose a starter company template.
Mission — set your starting budget, revenue target, optional
customer-count goal, and a deadline.
Team review — your AI C-suite debates whether the targets are
feasible and proposes adjusted numbers. You can keep yours, adopt
theirs, or counter-propose (re-runs only when you actually change a
number).
First move — the team proposes three concrete first-week
directives with day-by-day plans; pick one or ask the team
questions. Don't like them? Regenerate.
Provisioning — the dashboard pivots in once the picked
directive is activated and the team starts executing it.

To change company targets later, reopen the onboarding flow at
/ui/onboarding.html. The current Settings page does not edit mission /
target numbers yet.

Time in Kompany is virtual: one completed task = one virtual day,
so a paused app doesn't burn runway and a fast-working team isn't
penalised by the wall clock. The header's days: N/M vd tracks
virtual days against your deadline budget.

Installation

One-line install (recommended)

uvx kompany onboard --yes

That single command checks your environment, captures your LLM API key
(masked, stored in the encrypted vault), applies a starter company
template, and prints the first set of "what to do next" hints — all in
under 90 seconds. Pass --provider=..., --api-key=...,
--template=..., --directive="...", or --data-dir=/path to skip
specific prompts; with all of them plus --yes, the wizard runs fully
headless. See docs/context/onboarding.md
for the full step-by-step.

Prerequisites

Python 3.11+
An API key for at least one supported LLM provider (see Multi-Provider LLM Support)

Install from Source

git clone https://github.com/Fei2-Labs/Kompany.git
cd Kompany/kompany

# Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate   # macOS/Linux
# .venv\Scripts\activate    # Windows

# Install the package
pip install -e .

# For REST API support
pip install -e ".[api]"

# For MCP server support
pip install -e ".[mcp]"

# For development (tests)
pip install -e ".[dev]"

# Or install everything
pip install -e ".[api,mcp,dev]"

Set Your API Key

export ANTHROPIC_API_KEY=your-key-here

Or create a .env file in the kompany/ directory:

ANTHROPIC_API_KEY=your-key-here

To use other providers, set their API keys too (see Multi-Provider LLM Support).

For the encrypted credential vault, Kompany resolves a master key in this order: KOMPANY_VAULT_KEY env var → a file at <data_dir>/.vault-master.key (auto-generated, chmod 0600) → OS keychain (legacy) → freshly generated. The file-based default avoids repeated keychain prompts on unsigned desktop builds. Your provider API keys are then stored encrypted (Fernet) in the credential_vault table under that master key — never in plaintext on disk.

Verify Installation

kompany --help

You should see the list of available commands.

Quick Start

1. Initialize Your Company

kompany init --name "Acme SaaS" --product "AI invoice reconciliation" --balance 50 --stage solo

This creates the SQLite database, sets your starting balance to €50, and configures the company at the solo stage.

2. Send Your First Directive

kompany directive "Buy a Mac Studio M4 128GB, budget €50"

The CEO will classify this as an ACQUISITION directive, check the budget, find the shortfall, and create a revenue project with concrete revenue paths to fund the purchase.

3. Check Status

kompany status

See your company name, balance, active projects, total income, expenses, and AI costs.

4. View Projects

kompany projects

Lists all active projects including revenue projects created to fund missions.

5. Run a Strategic Debate

kompany debate "Should we build SSO or focus on self-serve onboarding?"

Runs a multi-agent debate with structured rounds, CoS synthesis, and a CEO decision.

6. Run Your First Workflow

kompany workflows show idea-validation                                                  # inputs, steps, cost
kompany workflows run idea-validation --json-inputs '{"idea": "Meal-prep kits for night-shift nurses"}' --dry-run   # preview, $0
kompany workflows run idea-validation --json-inputs '{"idea": "Meal-prep kits for night-shift nurses"}'             # run it

Three reference workflows ship in Core; each declares its inputs and shows its cost before spending. See Running Workflows.

Usage Guide

Kompany has four interfaces. All of them call the same KompanyEngine — same logic, same ledger, same results.

CLI Reference

The CLI is built with Typer and Rich for formatted terminal output.

`kompany init`

Initialize a new company. You'll be prompted interactively for any values not passed as options.

kompany init --name "My Startup" --product "AI tools for devs" --balance 100 --stage solo

Option	Description	Default
`--name`	Company name	(prompted)
`--product`	One-line product description	(prompted)
`--balance`	Starting balance in euros	(prompted)
`--stage`	Company stage: `solo`, `pre-seed`, `seed`, `series-a`	(prompted)

`kompany directive` — the CEO channel

Send a message into the CEO channel, the founder's conversation surface with the team. The CEO auto-routes each message and handles it autonomously.

kompany directive "Hire a freelance designer for the landing page, budget €500"

kompany directive "What's our current balance?"

kompany directive "Set up a CI/CD pipeline for the main repo"

Argument	Description
`text`	The message in natural language

Option	Description
`--session / -s`	Continue an existing channel session (clarify reply / gated GO context)
`--interactive / -i`	Answer clarify questions and GO/abandon prompts inline on stdin
`--config / -c`	Path to custom config file

The CEO routes each message into execute (clear → dispatch), clarify (ambiguous → asks back; your reply continues the same session, capped at 5 turns), or answer (a question → reply only). Expensive or master-tier actions hit a spend gate: the CEO posts a plan + estimated cost and nothing runs until you reply GO. Inspect history with kompany channel sessions and kompany channel show <session-id>.

What happens under the hood:

The message opens or continues a CEO-channel session
CEO classifies it (one of four types: ACQUISITION, STRATEGIC, OPERATIONAL, INFORMATIONAL) and a route (execute / clarify / answer)
CFO checks budget if needed (mechanical — no LLM cost); the spend gate pauses expensive/irreversible work for a GO
If budget is short, CEO creates a revenue project
AI costs are recorded in the ledger
The CEO's reply is recorded as a channel turn with its cost

`kompany status`

Display the current company state.

kompany status

Output includes:

Company name and product
Current balance
Total income, expenses, and AI costs
Number of active projects

`kompany projects`

List all active projects.

kompany projects

Shows project ID, name, type (revenue/operational/strategic), status, target amount, and funded amount for each project.

`kompany project`

Show details for a specific project, including its tasks and revenue paths.

kompany project abc12345

Argument	Description
`project_id`	The project ID (shown in `kompany projects` output)

`kompany debate`

Run a full multi-agent debate on a strategic question.

kompany debate "Should we raise a Series A or extend runway through revenue?"

The debate follows a structured protocol:

Round 1 — Independent positions (each agent argues from their domain)
Round 2 — Rebuttal & challenge (agents respond to each other)
Round 3 — Convergence (move toward consensus, flag hard lines) — only in 3-round mode
CoS Synthesis — Structured CEO brief
CEO Decision — Final call with rationale and next steps

Argument	Description
`question`	The strategic question to debate

`kompany ledger`

Show recent financial transactions.

kompany ledger
kompany ledger --limit 25

Option	Description	Default
`--limit / -n`	Number of entries to show	10

Each entry shows: timestamp, amount, balance after, description, and category (income, expense, ai_cost, allocation, refund).

`kompany execute`

Execute a revenue project's tasks autonomously using subagents.

kompany execute abc12345

Argument	Description
`project_id`	The project to execute

This decomposes the project into tasks, assigns subagents (Analyst, Builder, Researcher, Writer, Procurement), and runs them. AI costs for each task are tracked in the ledger.

REST API

Start the API server (requires pip install -e ".[api]"):

uvicorn kompany.interfaces.api:app --reload

The API runs at http://localhost:8000. Interactive docs at http://localhost:8000/docs.

Endpoints

Method	Endpoint	Description
`POST`	`/init`	Initialize a new company
`POST`	`/channel/send`	Send a message into the CEO channel (`text`, optional `session_id`) — canonical
`POST`	`/directive`	Backward-compat alias for `/channel/send`
`GET`	`/channel/sessions`	List channel sessions, newest first
`GET`	`/channel/sessions/{session_id}`	One session + its turns (full thread)
`POST`	`/channel/sessions/{session_id}/go`	Founder GO on a spend-gated session
`POST`	`/channel/sessions/{session_id}/abandon`	Abandon a session without executing
`GET`	`/channel/runs/{run_id}/cost`	Per-run AI cost (reload-restore reconcile)
`GET`	`/status`	Get company status
`GET`	`/projects`	List active projects
`GET`	`/projects/{project_id}`	Get a specific project
`GET`	`/ledger?limit=10`	Get recent ledger entries
`POST`	`/projects/{project_id}/execute`	Execute a project's tasks

Examples

Initialize:

curl -X POST http://localhost:8000/init \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme", "product": "AI tools", "balance": 50, "stage": "solo"}'

Send a message into the CEO channel:

curl -X POST http://localhost:8000/channel/send \
  -H "Content-Type: application/json" \
  -d '{"text": "Buy a Mac Studio M4 128GB, budget €50"}'

A clarify response carries a session_id — re-POST with it to continue. A gated response means the spend gate is waiting: POST /channel/sessions/{id}/go to execute, or /abandon to drop it.

Response:

{
  "status": "completed",
  "message": "Revenue project created to fund acquisition...",
  "project_id": "abc12345",
  "total_ai_cost": 0.18,
  "agents_used": ["CEO", "CFO", "CRO", "CMO", "CTO"]
}

Check status:

curl http://localhost:8000/status

View ledger:

curl "http://localhost:8000/ledger?limit=20"

MCP Server

Run as an MCP server for Claude Code, Cursor, or any MCP-compatible client (requires pip install -e ".[mcp]"):

kompany-mcp
# or
python -m kompany.interfaces.mcp_server

Available Tools

The server exposes 88 typed kompany_* tools covering directives,
approvals, projects, ledger, debates, glossary, health, backups,
credentials, channels, templates, and runtime control. The everyday core:

Tool	Parameters	Description
`kompany_init`	`name`, `product`, `balance` (default: 0.0), `stage` (default: "solo")	Initialize a new company
`kompany_directive`	`text`*, `session_id`	Send a message into the CEO channel (pass `session_id` to continue a clarify session)
`kompany_channel_sessions`	`state`, `limit`	List channel sessions, newest first
`kompany_channel_session`	`session_id`*	One session + its turns (full thread)
`kompany_channel_go`	`session_id`*	Founder GO on a spend-gated session
`kompany_channel_abandon`	`session_id`*	Abandon a session without executing
`kompany_status`	(none)	Get company status
`kompany_projects`	(none)	List active projects
`kompany_project`	`project_id`*	Get project details
`kompany_ledger`	`limit` (default: 10)	Get recent ledger entries
`kompany_debate`	`question`*	Run a multi-agent debate
`kompany_execute`	`project_id`*	Execute a project's tasks

Claude Code Configuration

Add to your Claude Code MCP settings:

{
  "mcpServers": {
    "kompany": {
      "command": "kompany-mcp",
      "env": {
        "ANTHROPIC_API_KEY": "your-key-here"
      }
    }
  }
}

Python SDK

Use Kompany programmatically in your own Python code:

from kompany import Kompany

# Initialize
k = Kompany()
k.init(name="Acme", product="AI tools", balance=50, stage="solo")

# Send a message into the CEO channel
result = k.directive("Buy a Mac Studio M4 128GB, budget €50")
print(result["message"])
print(f"AI cost: ${result['total_ai_cost']:.2f}")

# The channel namespace mirrors the REST /channel/* surface
result = k.channel.send("set up the thing")
if result["status"] == "clarify":          # CEO asked back — continue the session
    result = k.channel.send("the email one", session_id=result["session_id"])
if result["status"] == "gated":            # spend gate — review, then GO
    result = k.channel.go(result["session_id"])

# Check balance
print(f"Balance: €{k.balance():.2f}")

# View status
status = k.status()
print(f"Active projects: {status['active_projects']}")

# List projects
for project in k.projects():
    print(f"  {project['id']}: {project['name']} ({project['status']})")

# Get project details
project = k.project("abc12345")
print(project["plan"])

# View ledger
for entry in k.ledger(limit=5):
    print(f"  {entry['description']}: {entry['amount']}")

# Execute a revenue project
result = k.execute_project("abc12345")
print(result)

SDK Methods

Method	Returns	Description
`Kompany(config_path=None)`	—	Constructor. Optionally pass a config file path.
`init(name, product, balance=0.0, stage="solo")`	`None`	Initialize a new company
`directive(text, session_id=None)`	`dict`	Send a message into the CEO channel, get the result
`channel.send(text, session_id=None)`	`dict`	Send a message (opens/continues a session)
`channel.go(session_id)`	`dict`	Founder GO on a spend-gated session
`channel.abandon(session_id)`	`dict`	Abandon a session without executing
`channel.sessions(state=None, limit=50)`	`list[dict]`	List channel sessions, newest first
`channel.session(session_id)`	`dict \| None`	One session + its turns (full thread)
`status()`	`dict`	Company status (balance, projects, costs)
`projects()`	`list[dict]`	All active projects
`project(project_id)`	`dict \| None`	A specific project, or None
`balance()`	`float`	Current balance
`ledger(limit=10)`	`list[dict]`	Recent ledger entries
`execute_project(project_id)`	`dict`	Execute a project autonomously

Using with Claude Code

Claude Code connects to Kompany the same way every other agent runtime does — through the kompany-mcp server. Two install paths:

Plugin (one-click): install the Claude Code plugin (.claude-plugin/plugin.json). It registers the MCP server and adds a /kompany command:
```
/kompany "Buy a Mac Studio M4 128GB, budget €50"
```
Manual: add kompany-mcp to your MCP settings as shown in MCP Server above.

An optional thin skill (.claude/skills/kompany/SKILL.md) conveys the founder mental model; all capabilities live in the kompany_* MCP tools. See docs/USAGE_GUIDE.md § "Using with Claude Code" for details.

Directive Types

Every directive is classified by the CEO into one of four types:

Type	Triggers	Behavior
ACQUISITION	"Buy X", "Get X", "Hire X"	Must deliver X. Budget shortfall → revenue project. Never downgrade.
STRATEGIC	"Should we X?", "What's our approach to Y?"	CEO analysis or full multi-agent debate.
OPERATIONAL	"Set up X", "Configure Y", "Deploy Z"	CEO breaks into action steps and delegates to squad.
INFORMATIONAL	"What's our balance?", "Status", "How many projects?"	Query state directly. No LLM cost — mechanical CFO responds.

Autonomy Tiers

Tier	Max Spend	Examples	Approval
Auto-execute	€5	Research, analysis, internal planning	None needed
CEO-approved	€50	Small purchases, internal comms	CEO decides, Master informed
Master-approved	Unlimited	Large spend, legal, external-facing, irreversible	Must ask Master

Channels — Telegram, Email, Outbox

The engine is reachable beyond the CLI/desktop through channel adapters
(kompany channels …). Adapters never reason — they only translate
transport messages to and from the engine, which does all the thinking:

Telegram (inbound): chat with your company from your phone; messages
route through the same CEO channel as kompany directive.
Email triage (inbound): the team reads a connected inbox and turns
actionable mail into directives or approval items.
Outbox (outbound, drafts-only): agents draft posts/replies (X/Weibo
planned); nothing is published without the founder releasing it. Real
sending (e.g. SMTP email) is an EXTERNAL_ACTION at APPROVAL tier — it
never fires without explicit founder approval.

Anima — the Company Persona

A persona layer above the C-suite that makes the company feel alive without
contaminating its judgment:

Emotion state (valence/energy) is updated by pure code from real events
— income, task completions/failures, health alerts — and decays toward
neutral. No LLM calls.
Daily diary: at most one economy-tier LLM call per day distills the last
24h into a short first-person entry (cost booked to the ledger like
everything else).
Hard invariant: emotion shapes Anima's voice only. It is never
injected into C-suite, classification, or debate prompts — your CFO's
budget check doesn't get moody.

Self-Update Pipeline

The company can propose improvements to itself (kompany self-update …).
Proposals are tiered by blast radius, run in an isolated workspace, must
pass the test suite, and land as diffs in the approval inbox — the founder
reviews and applies; nothing self-modifies silently.

Multi-Agent Debates

Strategic directives can trigger a full multi-agent debate:

Question → Round 1: Independent positions (each exec argues from their domain)
         → Round 2: Rebuttal & challenge (execs respond to each other)
         → Round 3: Convergence (move toward consensus, flag hard lines)
         → CoS Synthesis (structured CEO brief)
         → CEO Decision (final call with rationale + next steps)

The number of rounds and participating agents depends on the company stage.

Stage Profiles

The framework adapts its agent roster and cost profile based on your company stage:

Stage	Active Agents	Debate Rounds	Max Cost
Solo founder	CEO, CTO, CPO, CFO, CoS	2	~$0.50
Pre-seed	CEO, CTO, CPO, CoS, CV	2	~$0.75
Seed	CEO, CTO, CPO, CMO, CRO, CoS, CV	3	~$1.50
Series A	All 11 agents	3	~$2.00

Multi-Provider LLM Support

Kompany supports multiple LLM providers. Any model tier (apex/primary/economy) can use any provider:

Provider	Example Models	Connection
Anthropic	Claude Opus 4, Sonnet 4, Haiku 4	Native `anthropic` SDK
OpenAI	GPT-4o, GPT-4.1, o3, o4-mini	`openai` SDK
Google Gemini	Gemini 2.5 Pro, 2.5/2.0 Flash	`openai` SDK (compatible endpoint)
GLM (Zhipu AI)	GLM-4 Plus, Air, Flash	`openai` SDK (compatible endpoint)
Kimi (Moonshot)	Moonshot v1, Kimi	`openai` SDK (compatible endpoint)
Custom	Any OpenAI-compatible model	`openai` SDK (your base URL)

Provider routing: if CUSTOM_LLM_BASE_URL is set, all model tiers route to that custom OpenAI-compatible endpoint (it wins regardless of model-name prefix — so gpt-5.5 or any model name your endpoint exposes works). Otherwise detection falls back to the model-name prefix (claude- → Anthropic, gpt-/o3/o4 → OpenAI, gemini- → Gemini, etc.).

Example: Use GPT-4o as primary

export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."

models:
  apex: "claude-opus-4-20250514"
  primary: "gpt-4o"
  economy: "gemini-2.0-flash"

Example: Use a custom OpenAI-compatible endpoint (e.g. a gateway)

export CUSTOM_LLM_BASE_URL="https://your-gateway.example.com/v1/"
export CUSTOM_LLM_API_KEY="sk-..."
# Point all three tiers at a model your endpoint serves:
export KOMPANY_MODEL_APEX="gpt-5.5"
export KOMPANY_MODEL_PRIMARY="gpt-5.5"
export KOMPANY_MODEL_ECONOMY="gpt-5.5"

In the desktop app you don't need env vars: pick custom (OpenAI-compatible) on the connection step, paste the base URL + key, and the wizard discovers available models from the endpoint's /models index. If those env vars (or a .env in the data dir) are present, the connection step auto-fills them.

Cost tracking works across all providers — each model has pricing data for accurate ledger entries.

Project Structure

kompany/
├── src/kompany/
│   ├── config/                   # Pydantic Settings, model-source config, workspaces
│   ├── core/                     # KompanyEngine + engine_parts/ (approvals, governance,
│   │   │                         #   distill, learning, channel routing, …)
│   │   ├── harness/              # Task execution vehicles: Claude Code, Codex,
│   │   │   │                     #   opencode, and the Kompany-native agentic loop
│   │   │   └── …                 #   + budget caps, safety, workspace isolation
│   │   ├── harness_execution/    # Executor, monitor, permission gate, outcomes
│   │   ├── self_update/          # Self-update pipeline (tiers, workspace, effects)
│   │   ├── debate.py             # Multi-agent debate engine
│   │   ├── anima.py              # Company persona (emotion + diary)
│   │   ├── ticker.py / watchdog.py / daemon_ops.py   # 24/7 tick loop
│   │   └── workflow_runner.py / step_executor.py     # Workflow YAML runtime
│   ├── llm/                      # Multi-provider client, cost ledger/preview/tracker
│   ├── agents/                   # 11 C-suite + 5 subagents + YAML souls + SoulAgent
│   ├── channels/                 # Telegram, email-in, outbox adapters (no LLM here)
│   ├── integrations/             # Real-action tools (SMTP email, approval-gated)
│   ├── plugins/                  # Plugin contract (5 ABCs) + entry-point loader
│   ├── state/                    # SQLite stores: ledger, projects, approvals, episodes,
│   │                             #   credentials vault, glossary, health, targets, …
│   ├── templates/                # 7 starter template seeds
│   ├── workflows/                # 3 reference workflow YAMLs
│   ├── web_ui/                   # Onboarding/settings/design web UI
│   └── interfaces/               # CLI (Typer, incl. anima/channels/daemon/founder/
│                                 #   self-update/workspace), REST API, MCP server
│                                 #   (88 typed tools), SDK, daemon
├── tests/                        # 1,500+ tests
├── pyproject.toml
└── README.md

Configuration

Environment Variables

Variable	Description	Required
`ANTHROPIC_API_KEY`	Anthropic API key	Yes (if using Claude models)
`OPENAI_API_KEY`	OpenAI API key	No
`GEMINI_API_KEY`	Google Gemini API key	No
`GLM_API_KEY`	Zhipu AI (GLM) API key	No
`KIMI_API_KEY`	Moonshot (Kimi) API key	No
`CUSTOM_LLM_API_KEY`	Custom endpoint API key	No
`CUSTOM_LLM_BASE_URL`	Custom OpenAI-compatible base URL (when set, all tiers route here)	No
`KOMPANY_MODEL_APEX` / `_PRIMARY` / `_ECONOMY`	Override the three model tiers (use the same value for all three with a custom endpoint)	No
`KOMPANY_VAULT_KEY`	Fernet master key for the credential vault (else a `.vault-master.key` file is auto-generated in the data dir)	No
`KOMPANY_DATA_DIR`	Data directory (DB, vault, `.env`)	No (defaults to `~/.kompany`; the desktop app uses its platform app-support dir)
`KOMPANY_DB_PATH`	SQLite database path	No (defaults to `./kompany.db`)
`KOMPANY_CONFIG_PATH`	YAML config file path	No

Unknown env vars are ignored (not an error), so your shell or .env
can carry unrelated keys without breaking engine startup. The desktop
app — launched from Finder/Explorer — doesn't inherit your shell
environment, so for it, place a .env in the data directory
(<data_dir>/.env).

Custom API connection in Settings

In Settings → Model Source, choose Custom API key to show the
Base URL and API key fields. Click Save API connection to update
the current engine; subsequent calls use the new connection. Calls already
running retain their existing connection. Other engine processes pick up the
change when restarted. Saving the connection does not change billing source
or select a model; those controls remain separate.

The saved key is never returned to the browser. Leave the key field blank to
keep it; enter it again when changing the URL. Local HTTP endpoints are supported.
Saving reads the endpoint's model list without generating a paid completion.
A warning means discovery failed, returned no models, or did not list the active
model; it does not mean the connection failed to save or inference was tested.

GET /settings/custom-llm returns base_url and api_key_configured.
PUT /settings/custom-llm accepts { "base_url": "…", "api_key": "…" }
and returns that status plus warning. These routes use dashboard authentication.

The connection is saved in the active YAML config with owner-only file permissions.
Explicit custom_llm.api_key and custom_llm.base_url values override
CUSTOM_LLM_API_KEY and CUSTOM_LLM_BASE_URL; omitted fields still use the
environment. Keep this file out of version control.

Company Config (YAML)

company:
  name: "Your Company"
  product: "One-line product description"
  stage: "solo"          # solo | pre-seed | seed | series-a

# Override model tiers (optional)
models:
  apex: "claude-opus-4-20250514"     # or "gpt-4o", "gemini-2.5-pro", etc.
  primary: "claude-sonnet-4-20250514"
  economy: "claude-haiku-4-20250414"

# Custom OpenAI-compatible endpoint (optional)
custom_llm:
  base_url: "https://my-endpoint.example.com/v1"
  api_key: "my-key"

Running Tests

cd kompany
python3 -m venv .venv          # first time only
source .venv/bin/activate
pip install -e ".[api,mcp,dev]"   # api extra is required: API tests import fastapi
python -m pytest tests/ -v

All 1500+ tests should pass (about 80 seconds on a laptop).

AI Cost Transparency

Every LLM call is a real expense. The engine tracks per-call cost and records it in the ledger:

AI cost for this directive: $0.18
  CEO classify:      $0.03
  CEO revenue plan:  $0.15
Balance before: €50.00 → Balance after: €49.82

Use kompany ledger to see all transactions including AI costs.

Open Core — Core / Pro / Cloud

Kompany follows an open-core model. The engine you see in this repo is
the whole engine — there is no crippled "community edition." Commercial
extensions live in a separate package.

Tier	What's in it	License	Where
Kompany Core (this repo)	Full agent engine, debate runtime, cost ledger, budget tracking, CLI, REST API, MCP server, plugin contract (5 stable ABCs), 11 base C-suite + 5 subagent souls, 7 starter templates, 3 reference workflows (`idea-validation`, `weekly-exec-review`, `landing-page-launch`)	AGPL-3.0 — free to run, modify, and fork for your own company; offering it to others as a network service requires sharing your modifications (or a commercial license)	`Fei2-Labs/Kompany`
Kompany Pro	Curated deep playbooks above the 7 Core seeds, specialist agent souls (industry-specific roles like SaaS Compliance Officer / Ecom Inventory Manager — additive over Core's 11+5, never replacement), business integrations (Stripe, Polar, Notion, Slack, …)	Proprietary	`Fei2-Labs/kompany-pro` (private repo, access via subscription or Early Backer grant)
Kompany Cloud	Hosted SaaS — managed runtime, dashboard, scheduling, persistence, integrations	TBD pricing	Not yet launched

Pro is additive, never replacement. Every Core artifact — the 11
C-suite souls, the 7 template seeds, the 3 reference workflows — is
permanent and fully functional. Pro adds net-new categories above them.
If a Core artifact has a bug, it's fixed in Core, not crowbar-replaced
by a Pro module.

Pro contents are public; Pro code is gated. The list of Pro modules
(workflow names, soul names, integration names) is published. Only the
source code stays behind authorization.

How Pro plugs in. Pro packages register contributions via Python
entry points defined by Core's plugin contract
(kompany.plugins.contract, v1.0.0). Discovery happens at engine init:

pip install kompany kompany-pro     # Pro from authorized index
python -c "from kompany.plugins.loader import discover; print(discover())"

Pro plugins appear alongside Core ones in the Templates picker, agent
registry, and workflow registry with no special-casing at call sites.
Version compatibility is enforced by pip dep pinning: a Core contract
major bump (kompany 0.x → 0.y) blocks pip install -U kompany until
a compatible Pro release ships. Intentional design — see
ADR-0002.

Early Backer grant. Supporters who backed Kompany before the public
OSS launch were promoted to the Kompany Early Backer tier — Core source
(AGPL-3.0, same as everyone) plus a window of Pro source access, Cloud
credit when Cloud ships, a private channel, and a roadmap-input call.

Why this model. The agent runtime is forkable in a week — gating it
would be performative. Real moat lives in curated workflows + Cloud
ops, which are content + operational, not gated by code obfuscation.
Why AGPL specifically: docs/why-agpl.md.

Contributing

See CONTRIBUTING.md for guidelines.

Fork the repository
Create a feature branch: git checkout -b feature/your-feature
Make your changes
Run tests: python -m pytest tests/ -v
Commit with a clear message
Push and open a PR against main

Support

If you find Kompany useful, consider supporting the project:

License

AGPL-3.0 · free for your own company · commercial license if you sell access to others — see LICENSE and Why AGPL?.