☭ SOVIET·CODE

"Your code. Under proper supervision." Centralized planning. Decentralized blame. Open source.

What is it

Soviet Code is an AI coding agent CLI that wraps Claude with a full Soviet bureaucracy. You issue directives. The Party plans, reviews, executes, and self-criticizes. Every decision is logged in the Nomenclature. Every plan goes through a Tribunal of three reviewers before a single line of code is written.

It runs the S·T·A·L·I·N pipeline — a six-phase agent loop built on top of Claude Code. It is open source, free, and extremely serious about everything.

Install

# npm
npm install -g soviet-code

# npx (no install)
npx soviet-code@latest

# brew (coming soon)
brew install soviet-code

Requirement: Claude Code CLI must be installed and authenticated.

Quick start

# In your project directory:
soviet init
soviet plan "fix auth middleware race condition"
soviet review          # Tribunal: 3 reviewers vote (2/3 required)
soviet work            # Execute first pending directive
soviet status          # Check pyatiletka progress
soviet inspect         # Mandatory self-criticism

The S·T·A·L·I·N pipeline

С → Т → А → Л → И → Н
│   │   │   │   │   └─ Номенклатура  (record to long-term memory)
│   │   │   │   └───── Инспекция     (mandatory self-criticism)
│   │   │   └───────── Лейбор        (execute directive)
│   │   └───────────── Аллокация     (constitute pyatiletka / plan)
│   └───────────────── Трибунал      (3-reviewer ensemble vote)
└───────────────────── Сбор данных   (surveillance / gather context)

| Phase | Command | Description | |-------|---------|-------------| | С Surveillance | soviet plan | Gathers context, composes the pyatiletka (task plan) | | Т Tribunal | soviet review | Three reviewers (Pioneer/Komsomol/Politburo) vote 2/3 | | А Allocation | (part of plan) | Gosplan prioritizes and sequences directives | | Л Labor | soviet work | Executes next pending directive via Claude | | И Inspection | soviet inspect | Mandatory self-criticism — "all is well" is not acceptable | | Н Nomenclature | (automatic) | All decisions logged to .soviet/nomenklatura.json |

soviet work is blocked until the Tribunal approves the plan. No exceptions. This is not configurable.

Party hierarchy (model tiers)

| Rank | Model | Duties | Motto | |------|-------|--------|-------| | Пионер (Pioneer) | Haiku | Quick reconnaissance, obvious issues | "Всегда готов!" | | Комсомолец (Komsomol) | Sonnet | Main labor, technical review | "Партия сказала — надо!" | | Политбюро (Politburo) | Opus | Strategic decisions, ideological review | "Политбюро решает." |

The Tribunal summons all three simultaneously. Two approvals = plan proceeds.

Configuration: politburo.toml

# politburo.toml — Party Directives
# Generated by: soviet init

[party]
name = "My Project"
version = "1.0.0"
model = "sonnet"      # pioneer=haiku | komsomolets=sonnet | cc=opus

[iron_curtain]
# Permitted external domains (exit visas, Article 44)
allowed_domains = []

[gosplan]
max_directives = 10   # Max directives per pyatiletka
language = "ru"       # Language for plans

Commands

| Command | Phase | Description | |---------|-------|-------------| | soviet init | — | Initialize .soviet/ directory and politburo.toml | | soviet plan "<task>" | С + А | Compose pyatiletka via Claude | | soviet review | Т | Convene 3-reviewer Tribunal (blocks work if rejected) | | soviet work [id] | Л | Execute next (or specified) directive | | soviet inspect | И | Run mandatory self-criticism on completed pyatiletka | | soviet status | — | Show pyatiletka progress with icons | | soviet nomenklatura | Н | View long-term memory log | | soviet purge [--hard] | — | Archive pyatiletka to gulag; --hard also clears nomenclature | | soviet rehabilitate | — | Restore last archived pyatiletka from gulag |

Госплан — multi-agent conductor

soviet start launches Госплан, a Soviet-themed multi-agent orchestration system embedded in Soviet Code. Six autonomous agents run in parallel, each with a dedicated role, communicating via file-based messaging.

soviet init       # creates politburo.toml (interactive: sets up Госплан on first run)
soviet start      # launch all six departments + optional Telegram bridge
soviet status     # check if Госплан is running (silent HTTP probe)

On first run, soviet start prompts for:

• Working directory (where depts/ will live)
• Telegram bot token (optional — skip to disable bridge)
• Telegram chat ID

Config is saved to politburo.toml under [gosplan] and [gosplan.telegram].

Departments (отделы)

| Dept | Role | Model | |------|------|-------| | gensek | General Secretary — coordination, delegation | Sonnet | | razvedka | Intelligence — research, investigation | Sonnet | | stakhanovtsy | Stakhanovites — implementation, commits | Sonnet | | inspektsiya | Inspection — QA, review | Haiku | | agitprop | Agitprop — propaganda, content | Sonnet | | tovarishch | Comrade — principal channel (Telegram) | Haiku |

Telegram bridge

When configured, Госплан bridges your Telegram channel to the tovarishch department:

• Messages you send → written to tovarishch/inbox/
• Messages from tovarishch/outbox/ → delivered to you via Telegram bot

Requirements

• Claude Code CLI installed and authenticated
• Node.js 18+ (for the conductor)

Local state

.soviet/
├── pyatiletka.json     # Current plan (directives + status)
├── nomenklatura.json   # Long-term memory (all phases logged)
└── gulag/              # Archived / purged pyatiletkas
politburo.toml          # Party configuration

IDEOLOGY.md

The 55-article Decree of the Central Computing Committee governs all behavior: terminology, anti-patterns (🌽 Kukuruzization, Potemkin Villages), operating modes (НЭП, Perestroika, Military Communism), and the single rule that holds everything together:

Every line of code, every comment, every terminal output — simultaneously funny, useful, and technically correct. Two out of three is self-criticism. One out of three is a formal reprimand.

Contributing

See CONTRIBUTING.md.

License

MIT — see LICENSE.

Слава роботам. ☭