You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
MiniCode Python is the Python implementation in the MiniCode family. The main
22
-
project is [LiuMengxuan04/MiniCode](https://github.com/LiuMengxuan04/MiniCode);
23
-
this repository now focuses on a Python-first agent runtime with cybernetic
24
-
control, adaptive memory, durable sessions, rewindable local edits, and
25
-
testable product surfaces for real local use.
21
+
<palign="center">
22
+
<imgalt="MiniCode Python terminal hero showing memory, session, rewind, and readiness"src="./docs/assets/readme/minicode-terminal-hero.svg"width="100%">
23
+
</p>
26
24
27
-
Instead of treating context pressure, tool failures, memory noise, and cost
28
-
drift as prompt-only problems, MiniCode Python measures them during execution
29
-
and feeds those signals back into runtime decisions.
25
+
<palign="center">
26
+
<em>Memory / Session / Rewind / Readiness: the runtime is part of the product.</em>
27
+
</p>
30
28
31
-
## Why It Exists
29
+
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.
32
30
33
-
Most coding agents are model wrappers: prompt in, tool calls out, hope the loop
34
-
stays healthy. MiniCode Python is built around a different idea:
31
+
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.
35
32
36
-
> a coding agent should observe itself while it works, then adjust its own
37
-
> context, memory, verification, concurrency, and recovery behavior.
33
+
## At a Glance
38
34
39
-
That makes this repository useful as:
35
+
MiniCode Python is for you if you want:
40
36
41
-
- a local coding-agent implementation you can inspect end to end;
42
-
- a Python research bed for agent control, memory, and verification loops;
43
-
- a companion implementation to the TypeScript MiniCode main repo;
44
-
- a practical place to test ideas before they become larger platform features.
37
+
- a terminal coding agent that behaves like a runtime, not a chat window;
38
+
- durable sessions you can inspect, replay, resume, and summarize;
39
+
- a memory stack that can protect working context and re-inject relevant project knowledge;
40
+
- safe local editing with checkpoints, rewind preview, and recovery flows;
41
+
- explicit signals for verification, widening, provider readiness, and failures.
45
42
46
-
## Highlights
43
+
If you only remember one thing, remember this:
47
44
48
-
| Area | What MiniCode Python Adds |
49
-
| --- | --- |
50
-
| Runtime control |`TurnKernel`, `CyberneticOrchestrator`, and runtime profiles (`single`, `single-deep`) coordinate phase-aware execution, widening, verification gates, and recovery. |
Control --> Actions["Runtime actions<br/>compact, cap concurrency,<br/>adjust budget, inject memory,<br/>recover, checkpoint, rewind"]
71
-
Actions --> Loop
72
-
```
51
+
> the runtime should be observable, recoverable, and testable, not just clever.
73
52
74
-
The main loop now drives the orchestrator lifecycle directly and layers it with
75
-
the turn kernel, runtime profiles, and product surfaces:
53
+
That changes the product priorities:
76
54
77
-
-`wire_memory()`
78
-
-`wire_healing()`
79
-
-`inject_memories()`
80
-
-`step_start()`
81
-
-`step_end()`
82
-
-`reflect_on_task()`
83
-
-`derive_turn_step_policy()`
84
-
-`activate_widening()`
85
-
-`record_runtime_event()`
55
+
| Priority | What it means here |
56
+
| --- | --- |
57
+
| Session-first | Sessions can be inspected, replayed, resumed, and summarized. |
58
+
| Recovery-first | File edits are checkpointed, previewable, and rewindable. |
59
+
| Runtime-first | Widening, verification, compaction, and stop reasons are explicit. |
60
+
| Local-first | The agent is built around real repos, local tools, and terminal workflows. |
86
61
87
-
This keeps controller initialization, memory injection, per-step observation,
88
-
feedback, self-healing, checkpointing, verification, and post-task reflection
89
-
tied to the same runtime surface.
62
+
## Why MiniCode Python
90
63
91
-
## Repository Status
64
+
| Area | What MiniCode Python emphasizes |
65
+
| --- | --- |
66
+
| Durable sessions | Inspect, replay, resume, and summarize live or saved sessions with local commands. |
67
+
| Memory as a first-class system | Protect active task context, re-inject project knowledge, compact with memory awareness, and persist useful reflections over time. |
Explain this repository and tell me which commands matter most for day-to-day use.
109
+
```
110
+
111
+
You should expect the normal MiniCode loop here: inspect repo state, explain findings, then let you inspect, replay, or continue the session.
112
+
113
+
### 3. Inspect what the runtime is doing
114
+
115
+
```text
116
+
/session
117
+
/memory
118
+
/readiness
119
+
```
120
+
121
+
### 4. Replay or recover if needed
122
+
123
+
```text
124
+
/session-replay
125
+
/checkpoints
126
+
/rewind-preview
121
127
```
122
128
123
-
Or run the module directly:
129
+
### 5. Run one-shot headless mode
124
130
125
131
```bash
126
-
python -m minicode.main
132
+
minicode-headless "Explain what this repo does."
127
133
```
128
134
129
-
Useful local product surfaces now available from the CLI and TUI include:
135
+
## Typical Workflow
130
136
131
-
-`/session`, `/sessions`, `/session-replay`
132
-
-`/checkpoints`, `/rewind`, `/rewind-preview`
133
-
-`/readiness`
137
+
```mermaid
138
+
flowchart LR
139
+
Start["Start local task"] --> Run["Run minicode-py"]
140
+
Run --> Work["Agent reads, edits, tests, and reports"]
141
+
Work --> Inspect["Inspect with /session, /memory, or /readiness"]
142
+
Inspect --> Replay["Replay with /session-replay"]
143
+
Inspect --> Recover["Preview or use /rewind if edits go wrong"]
144
+
Replay --> Continue["Resume or continue the next turn"]
145
+
Recover --> Continue
146
+
```
147
+
148
+
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.
149
+
150
+
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.
151
+
152
+
## Everyday Commands
153
+
154
+
If you only use six commands at first, use these: `/session`, `/sessions`, `/session-replay`, `/memory`, `/rewind-preview`, and `/readiness`.
155
+
156
+
| Command | What it does |
157
+
| --- | --- |
158
+
|`/session`| Show the current live session snapshot. |
159
+
|`/sessions`| List saved sessions for the current workspace. |
160
+
|`/session-replay`| Replay the current or a saved session with transcript and runtime context. |
161
+
|`/memory`| Show memory system status for the current workspace. |
162
+
|`/checkpoints`| Show checkpoint history for the current or a saved session. |
163
+
|`/rewind-preview`| Preview what a rewind would restore before changing files. |
164
+
|`/rewind`| Rewind the latest edit group, a step count, or a checkpoint id. |
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.
170
+
171
+
The active package is the root `minicode/` package configured by `pyproject.toml` as `minicode-py`.
0 commit comments