mixer-system 0.2.4

MixerSystem workflow engine package

Mixer System

Overview

Mixer System is an AI workflow engine for software development. The core idea is to split work into six discrete steps — task, plan, work, update, upgrade, and report — with each step backed by its own customizable workflow.

Each workflow is powered by a chain of specialized agents — builders, reviewers, testers, routers, formatters — that use the project's documentation (_name.md module docs) and rule files (.mixer/rules/) for context.

All work happens inside session folders (.mixer/sessions/), where artifacts are created for each step - task.md, plan.md, work.md, update.md, upgrade.md, report.md. One folder = one unit of work. Session folder holds all artifacts + logging for all agent actions. Workflows can run in 6-step sequence, or skip steps, or run individually in a fresh folder.

Docs and rules are scoped to modules so that agents only receive context relevant to the modules a task targets. A module is any folder in your project that contains a _name.md module doc file. Optionally, you can add rule files - .mixer/rules/<workflow_type>/<module>.md - to control how each workflow's agents behave.

Workflows are called through the Studio web UI (mixer studio), or via the Claude Code skill through agent conversation.

How to Use

Run mixer studio to open the web UI. From there you can create and manage sessions, run workflows, and view artifacts as they're produced.

Each workflow reads the project's docs, rules, existing artifacts in the session, and additional instructions that you pass to it.

Running a workflow when its artifact already exists is a revision - the workflow treats it as an update rather than a fresh build.

Workflows support lite mode (smaller model, faster and cheaper) and multiple providers (Claude, Gemini, Codex, or random).

You can call any workflow on its own — create a new session folder and jump straight to plan, building code, or update docs, or upgrade rules.

It is recommended to commit before running a workflow, so you have a clean checkpoint to revert to. It is also recommended to create a new git branch for each session folder — one branch per task.

Session folders are meant to be shared across teams via git. Sessions that start with local- (the default when creating from Studio) are gitignored for scratch work.

More things you can do in Mixer Studio

• Create, rename, archive, and delete sessions.
• View the agent trace log — a live feed of every agent call.
• Set which modules a session targets — each session has a module tree where you check/uncheck which parts of the project the agents should see. Defaults are set automatically by the router agent.
• Queue workflows inside the same session — when you start a workflow while another is already running, it gets queued and runs automatically when the current one finishes.
• Import a task from Linear into a session, or export a session's task back to Linear. Requires LINEAR_API_KEY in your .env and team_prefix + team_id in .mixer/settings.json.
• Push changes — scans all sessions that have a report.md, uses the report as the git commit message, archives those sessions, and pushes to remote.

Workflows

Task:

• Takes instructions and structures them into task.md. Single builder call.
• If task.md already exists, the builder revises it.

Plan:

• Reads task.md and other artifacts (and/or direct user instructions), produces plan.md.
• Builder drafts → reviewers check → failed reviews loop back to the builder.
• max_revisions controls review cycles (default 2, set to 0 to skip review).
• branch_count runs N builders in parallel (default 1). When >= 2, a merger synthesizes the drafts into feedback and the builder writes the final plan from that.
• If plan.md already exists, the builder revises it.

Work:

• Reads plan.md and other artifacts (and/or direct user instructions), produces work.md.
• Builder implements code → tester validates → failed tests loop back.
• max_test_iterations controls build-test cycles (default 5, set to 0 to skip testing).
• If work.md already exists, the builder revises it.

Update:

• Reads work.md and other artifacts (and/or direct user instructions), and edits module doc files directly. update.md is a report of what changed.
• If update.md already exists, the builder revises it.

Upgrade:

• Reads agent logs (agent_trace.log, agent_raw.log) (and/or direct user instructions), and edits/creates rule files directly. upgrade.md is a report of what changed.
• If upgrade.md already exists, the builder revises it.

Report:

• Reads all session artifacts and produces report.md — a summary of what was done, formatted as a conventional commit message. Single builder call.
• If report.md already exists, the builder revises it.

Setup

Install the package:

pip install mixer-system

Place a _name.md file (e.g., _mymodule.md) in any folder you want to declare as a module. The module name comes from the filename — no frontmatter needed. Linear integration (optional): Set LINEAR_API_KEY in your .env and configure team_prefix and team_id in .mixer/settings.json. Then run sync to register everything:

mixersystem sync

This scans for _*.md module doc files, builds the module tree into .mixer/settings.json, and syncs the coordinator skill to .claude/skills/mixer/SKILL.md. Re-run sync after upgrading the package.

Start Mixer Studio:

mixer studio

This opens the web UI on http://localhost:8420.