MiniCode Python

A lightweight local coding agent for developers who want durable terminal workflows, not just a chat wrapper.

Chinese | MiniCode Main Repo | Python Repo

Real MiniCode frontend demo, not a mock: the landing page now reflects the current Python runtime and shows memory, session, rewind, and readiness as first-class product surfaces.

MiniCode Python is the Python runtime in the MiniCode family. It is built for local development where the agent needs to survive long sessions, keep its state inspectable, recover from bad edits, and show what it is doing while it works.

If Claude Code represents the polished terminal-agent experience, MiniCode Python is the lightweight, local-first version that leans harder into runtime transparency, durable sessions, memory-backed continuity, rewindability, and verifiable behavior.

The screenshot above is rendered from the real MiniCode frontend demo. It highlights the four product promises we care about most on day one: memory that keeps context alive, sessions you can inspect and replay, rewind flows that make local edits safer, and readiness checks that tell you whether the runtime is actually ready to work.

At a Glance

MiniCode Python is for you if you want:

• a terminal coding agent that behaves like a runtime, not a chat window;
• durable sessions you can inspect, replay, resume, and summarize;
• a memory stack that can protect working context and re-inject relevant project knowledge;
• safe local editing with checkpoints, rewind preview, and recovery flows;
• explicit signals for verification, widening, provider readiness, and failures.

If you only remember one thing, remember this:

MiniCode Python is optimized for local trust: you should be able to inspect the work, recover the edits, and understand why the agent stopped.

Why This Repo Exists

Most coding-agent READMEs lead with model access and feature lists. MiniCode Python is organized around a different promise:

the runtime should be observable, recoverable, and testable, not just clever.

That changes the product priorities:

Why MiniCode Python

What You Can Do Today

With the current repository state, you can already:

• run an interactive terminal agent with minicode-py;
• run a single-shot command with minicode-headless;
• inspect the current session with /session;
• browse previous sessions with /sessions;
• replay a session with /session-replay;
• inspect memory state with /memory;
• inspect checkpoints with /checkpoints;
• preview or execute rewinds with /rewind-preview and /rewind;
• inspect provider and fallback health with /readiness.

3-Minute Demo

0. What you need

• Python 3.11+
• a local terminal on Windows, macOS, or Linux
• model/provider credentials if you want live model execution

1. Install and launch

git clone https://github.com/QUSETIONS/MiniCode-Python.git
cd MiniCode-Python
python -m pip install -e .[dev]
minicode-py

2. Ask it to do a real repo task

Explain this repository and tell me which commands matter most for day-to-day use.

You should expect the normal MiniCode loop here: inspect repo state, explain findings, then let you inspect, replay, or continue the session.

3. Inspect what the runtime is doing

/session
/memory
/readiness

4. Replay or recover if needed

/session-replay
/checkpoints
/rewind-preview

5. Run one-shot headless mode

minicode-headless "Explain what this repo does."

Typical Workflow

flowchart LR
    Start["Start local task"] --> Run["Run minicode-py"]
    Run --> Work["Agent reads, edits, tests, and reports"]
    Work --> Inspect["Inspect with /session, /memory, or /readiness"]
    Inspect --> Replay["Replay with /session-replay"]
    Inspect --> Recover["Preview or use /rewind if edits go wrong"]
    Replay --> Continue["Resume or continue the next turn"]
    Recover --> Continue

The main point is simple: MiniCode Python is not trying to hide the runtime. It lets you see the work, inspect the state, and recover from mistakes without manually cleaning everything up.

That same philosophy applies to memory: active task context is protected, durable project knowledge can be re-injected when it matters, and compaction is allowed to reuse memory instead of blindly dropping context.

Everyday Commands

If you only use six commands at first, use these: /session, /sessions, /session-replay, /memory, /rewind-preview, and /readiness.

Current Status

This repository is past the prototype stage. It already behaves like a usable local product, but it is still being tightened into a more polished lightweight Claude Code style experience.

The active package is the root minicode/ package configured by pyproject.toml as minicode-py.

Current local verification result:

1030 passed, 2 skipped, 3 warnings

Verification command:

python -m compileall -q minicode tests
pytest -q

Current state, honestly:

• core runtime, session, replay, checkpoint, rewind, and readiness surfaces are in good shape;
• memory is not bolted on: working memory, project memory, memory injection, and memory-aware compaction are already in the runtime path;
• provider and fallback diagnostics are much clearer than before;
• real provider availability still depends on your local credentials and configured channels;
• the project is usable today, but it is still evolving toward a more polished lightweight Claude Code experience.

The 3 warnings are unregistered pytest.mark.benchmark markers in benchmark tests. They are not failing behavior.

Architecture

flowchart LR
    User["User task"] --> Loop["agent_loop.py"]
    Loop --> Kernel["turn_kernel.py<br/>phase policy, widening,<br/>verification gate"]
    Loop --> Memory["Memory stack<br/>working_memory.py,<br/>memory.py, memory_pipeline.py"]
    Kernel --> Tools["Local tools<br/>files, search, edit, shell"]
    Tools --> Loop
    Memory --> Loop

    Loop --> Signals["Signals<br/>context, cost, errors,<br/>progress, provider state"]
    Signals --> Orchestrator["CyberneticOrchestrator"]
    Orchestrator --> Actions["Runtime actions<br/>compact, checkpoint, rewind,<br/>adjust budget, recover, reflect"]
    Actions --> Loop

What matters is not the diagram itself. What matters is that runtime state is treated as something explicit:

• the loop can widen instead of silently stalling;
• verification can block a premature "done";
• memory can preserve task-critical context and re-inject project knowledge instead of relying only on the current chat window;
• session state can survive process boundaries;
• rewind can reverse local edits instead of asking you to clean them up by hand;
• readiness can tell you whether failure is local logic or provider availability.

Repository Guide

Core Modules

MiniCode Family

Documentation

Start here if you want the deeper implementation and productization record:

• Chinese README
• Optimization Summary
• Memory Theory
• Minicode-lite Productization Design
• Minicode-lite Build Plan
• Minicode-lite Verify Report
• Main MiniCode Repository

Design Principles

• Keep the runtime inspectable.
• Treat memory as a controllable runtime subsystem, not an afterthought.
• Prefer measured signals over prompt folklore.
• Make recovery a product feature, not a manual cleanup step.
• Treat verification as part of execution, not just reporting.
• Keep docs aligned with implemented behavior, not future ambition.