Lykos

Status: under active development. Lykos is pre-release (0.0.1). Features are incomplete, commands and configuration may change without notice, and some providers are untested against live accounts. Use it on code you have committed, and expect rough edges.

Lykos is a coding agent for the terminal, built on the Pi runtime. It is built to be delegated to: an orchestrator hands it a task, and Lykos does the work behind an approval gate, records every model call, and reports what it verified.

• Made for orchestrator–worker workflows. Over MCP, an orchestrator starts sessions without waiting (lykos_start), checks on them (lykos_status), steers or stops them, and gets a result that separates what was verified from what is only the agent's claim.

• Fast to answer. A warm pool of session processes serves MCP calls without a cold start, and rarely used tools stay out of the prompt until searched.

• Efficient with tokens. The prompt prefix stays byte-identical for the whole session so provider caches keep hitting, and long sessions are pruned and compacted in place.

• Accountable. Every call lands in a SQLite ledger with its tokens, cache reads and writes, and cost, so spend is a query rather than a guess.

• Customizable. Specialists, skills, extensions, permission rules and models are set in YAML, per user or per project.

It runs three ways:

• Standalone, as a full-screen terminal UI or a one-shot task runner.

• As an MCP worker under an orchestrating agent, which calls Lykos specialists as its own tools.

• Under human supervision through a desktop app. Not built yet.

Features

• An approval gate by default. Three permission modes (manual, accept-edits, auto), remembered per project, plus path rules where deny always wins. Secret files and .git/ are protected out of the box.

• Specialists. Named bundles of model, tools, skills, prompt and permissions: plan, build, explore, general, review, test-writer, implementer, or your own in YAML. Switch mid-session.

• A full tool set. Hash-anchored edit, grep, glob, ast_grep / ast_edit, an lsp client, background jobs (hub), web_search (keyless by default) and web_fetch, github, eval, memory tools and security_scan. Rarely used tools stay out of the prompt until searched.

• A ledger. Every model call is recorded in SQLite with its tokens, cache reads and writes, and cost. lykos show, lykos cost and lykos tools read it.

• Nothing is deleted. Every session is archived and resumable. Checkpoints let you rewind the working tree to any turn without touching your branch.

• Sealed TDD. A test writer's failing tests are signed; an implementer cannot change them, only dispute them.

• Questions go up, not out. A delegated session asks its coordinator, not a terminal nobody is watching, and the coordinator answers or rules on disputes.

• Model access. Pools of API keys and OAuth logins per provider, with rotation and cooldown when a credential hits its limit.

• Optional containment. Run a session's commands inside Docker or Podman. Off unless you ask.

• Memory. The agent may propose a lesson; only you accept it.

Related MCP server: deepseek_harness

Requirements

• Node.js 22 or newer

• git

• Docker or Podman, only if you want containment

Lykos is developed on Windows. Other platforms are less tested.

Install

Lykos is not on npm yet. Install from source:

git clone https://github.com/rakun68/Lykos.git
cd Lykos
npm install
npm run build
npm link

npm link puts the lykos command on your PATH. Check the install:

lykos --version

Quick start

In the project you want to work on:

lykos init

This creates .lykos/config.yaml. The default model is DeepSeek. Give Lykos a key, either through the DEEPSEEK_API_KEY environment variable or its credential store (the key is read from stdin):

lykos login deepseek --api-key

For OAuth providers, run lykos login <provider>. Then check the setup:

lykos doctor

Start the terminal UI:

lykos

Or run one task and exit:

lykos run "add a --verbose flag to the CLI and a test for it"

A task run this way works on a branch and worktree of its own, so your working tree is not touched.

Common commands

Use Lykos as an MCP worker

Any MCP client can run lykos mcp over stdio. To register Lykos for a project:

lykos export claude

This adds lykos to the project's .mcp.json and writes one agent file per Lykos specialist. The orchestrator can then call lykos_<specialist> tools, or start sessions in the background with lykos_start and follow them with lykos_status. The contract is in docs/reference/mcp.md.

Configuration

Configuration is layered: shipped defaults, then ~/.lykos/config.yaml, then the project's .lykos/config.yaml, then the specialist, environment variables and flags. Runtime state lives in .lykos/; lykos init adds the ledger, sessions and cache to your .gitignore. The keys are in docs/reference/cli-and-config.md.

Documentation

• docs/reference/: CLI and configuration, the terminal UI, sessions and archive, specialists, model access, the MCP contract, the ledger

• docs/adr/: architecture decisions and why they were made

• GLOSSARY.md: the project's terms

• AGENTS.md: orientation for contributors and coding agents

Coming next

• Rust where it counts. Rewriting hot-path modules in Rust for startup time and speed.

• Detaching from Pi. Lykos becomes its own fork of Pi rather than depending on it. It runs alongside an existing Pi install and no longer needs a .pi/ directory.

• Lykos orchestrating Lykos. Running a task, then a whole phase of tickets, through review cycles from the CLI.

• A rebuilt terminal UI with a command palette, model picker and inline diffs, then a desktop supervisor.

License

MIT. Some files contain copied MIT-licensed code: see docs/copied-code.md.