303 lines
6.7 KiB
Markdown
303 lines
6.7 KiB
Markdown
# cc-slim
|
|
|
|
`cc-slim` is a deliberately small coding harness in the style of Claude Code / Codex.
|
|
|
|
It focuses on the core local loop only:
|
|
|
|
- REPL / CLI entry
|
|
- model-driven agentic loop
|
|
- streamed text output
|
|
- small tool surface
|
|
- session persistence
|
|
- structured project memory
|
|
- manual `/dream` consolidation
|
|
- mode / permission / workspace control
|
|
|
|
The project is intentionally not a full platform. It is built to be readable, easy to explain in an interview, and small enough to reason about end to end.
|
|
|
|
## What It Actually Implements
|
|
|
|
- Agentic loop with model -> tool call -> tool execution -> tool result -> final answer
|
|
- Streaming REPL output with tool call / tool result status lines
|
|
- Built-in tools:
|
|
- `Read`
|
|
- `Glob`
|
|
- `Grep`
|
|
- `Write`
|
|
- `Edit`
|
|
- `Bash`
|
|
- Slash command router for session, memory, mode, and permissions
|
|
- Session persistence with history / resume
|
|
- Structured Memory v2 stored as Markdown
|
|
- Manual Dream v1 to consolidate the current session into Memory
|
|
- Permission gate for `Write`, `Edit`, and `Bash`
|
|
- `build` / `plan` mode
|
|
- workspace boundary as the default operating scope
|
|
- explicit `--workspace` support
|
|
|
|
## What It Does Not Implement
|
|
|
|
- sandboxing
|
|
- sub-agents or coordinator routing
|
|
- vector database or Mem0 backend
|
|
- automatic background dream / consolidation
|
|
- multi-session dream
|
|
- complex skill execution framework
|
|
- fine-grained path allowlists / denylists
|
|
|
|
Those are intentional omissions, not missing TODOs.
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
uv sync
|
|
```
|
|
|
|
Set credentials through environment variables or `.cc-slim.toml` in the `cc-slim` program directory.
|
|
|
|
`--workspace` only changes the target project. It does not change where `cc-slim` reads its own config.
|
|
|
|
## Quick Start
|
|
|
|
Run inside the target project directory:
|
|
|
|
```bash
|
|
uv run cc-slim
|
|
```
|
|
|
|
Run from elsewhere but target a workspace explicitly:
|
|
|
|
```bash
|
|
uv run cc-slim --workspace E:\04test
|
|
```
|
|
|
|
Single-shot prompt:
|
|
|
|
```bash
|
|
uv run cc-slim "what does this repo do?"
|
|
```
|
|
|
|
List history for the current workspace:
|
|
|
|
```bash
|
|
uv run cc-slim --history
|
|
```
|
|
|
|
Resume a prior session:
|
|
|
|
```bash
|
|
uv run cc-slim --resume 1
|
|
```
|
|
|
|
Skip confirmation for high-risk tools:
|
|
|
|
```bash
|
|
uv run cc-slim --auto-approve
|
|
```
|
|
|
|
## REPL Commands
|
|
|
|
Session:
|
|
|
|
- `/history`
|
|
- `/resume <id-or-index>`
|
|
- `/new`
|
|
- `/clear` as an alias for `/new`
|
|
|
|
Memory:
|
|
|
|
- `/memory`
|
|
- `/remember <text>`
|
|
- `/dream`
|
|
|
|
Mode:
|
|
|
|
- `/mode`
|
|
- `/mode build`
|
|
- `/mode plan`
|
|
- `/build`
|
|
- `/plan`
|
|
|
|
Permissions:
|
|
|
|
- `/permissions`
|
|
- `/permissions auto-on`
|
|
- `/permissions auto-off`
|
|
|
|
## Runtime Model
|
|
|
|
There are two roots in the current code:
|
|
|
|
- program root
|
|
- the `cc-slim` repository itself
|
|
- used for reading `.cc-slim.toml`
|
|
- workspace root
|
|
- the project being operated on
|
|
- used for `AGENTS.md`, `SKILLS`, `Session`, `Memory`, permissions, and boundary checks
|
|
|
|
The system prompt is assembled in this order:
|
|
|
|
1. `src/cc_slim/system.md`
|
|
2. runtime summary
|
|
3. workspace `AGENTS.md`
|
|
4. workspace `SKILLS/*.md`
|
|
5. structured `Memory`
|
|
|
|
This keeps responsibilities separate:
|
|
|
|
- `system.md`
|
|
- built-in harness behavior
|
|
- workspace `AGENTS.md`
|
|
- workspace / project rules
|
|
- `Memory`
|
|
- long-lived project knowledge and user preferences
|
|
- `Session`
|
|
- raw conversation history
|
|
- `Dream`
|
|
- manual consolidation from the current session into Memory
|
|
|
|
## Mermaid Architecture
|
|
|
|
```mermaid
|
|
flowchart TD
|
|
U[User] --> CLI[CLI / REPL in main.py]
|
|
CLI --> CMD[Slash command router in commands.py]
|
|
CLI --> LOOP[Agent loop in engine.py]
|
|
|
|
CMD --> SESS[SessionStore]
|
|
CMD --> MEM[MemoryStore]
|
|
CMD --> MODE[ModeState]
|
|
CMD --> PERM[PermissionChecker]
|
|
CMD --> DREAM[/dream -> Agent.dream/]
|
|
|
|
SYS[system.md] --> PROMPT[Prompt Assembly]
|
|
RT[Runtime Summary] --> PROMPT
|
|
AG[workspace AGENTS.md] --> PROMPT
|
|
SK[workspace SKILLS/*.md] --> PROMPT
|
|
MEM --> PROMPT
|
|
|
|
PROMPT --> LOOP
|
|
SESS --> LOOP
|
|
|
|
LOOP --> TOOLS[Read / Glob / Grep / Write / Edit / Bash]
|
|
PERM --> TOOLS
|
|
MODE --> PERM
|
|
BOUNDARY[Workspace Boundary] --> PERM
|
|
|
|
LOOP --> STREAM[Streaming text + tool events]
|
|
STREAM --> CLI
|
|
|
|
DREAM --> MEM
|
|
SESS --> CMD
|
|
```
|
|
|
|
## Tools
|
|
|
|
Current tool boundaries are intentionally narrow:
|
|
|
|
- `Read`
|
|
- reads a text file inside the workspace
|
|
- `Glob`
|
|
- matches paths inside the workspace
|
|
- `Grep`
|
|
- plain-text contains search inside the workspace
|
|
- not regex-based
|
|
- returns up to 20 matches
|
|
- `Write`
|
|
- create or overwrite a full file
|
|
- `Edit`
|
|
- overwrite an existing file with full new content
|
|
- `Bash`
|
|
- runs a shell command with the workspace as `cwd`
|
|
|
|
There is no partial-edit patch tool, no AST manipulation, and no shell sandbox.
|
|
|
|
## Modes, Permissions, and Boundary Control
|
|
|
|
`build` mode is the normal execution mode.
|
|
|
|
`plan` mode is read-only in practice:
|
|
|
|
- allowed by default:
|
|
- `Read`
|
|
- `Glob`
|
|
- `Grep`
|
|
- hard-blocked:
|
|
- `Write`
|
|
- `Edit`
|
|
- `Bash`
|
|
|
|
Permission behavior:
|
|
|
|
- `Read`, `Glob`, `Grep` are auto-allowed
|
|
- `Write`, `Edit`, `Bash` require confirmation unless `--auto-approve` or `/permissions auto-on` is enabled
|
|
- hard boundaries are checked before approval:
|
|
- `plan` mode restrictions
|
|
- obvious workspace-external `Bash` targets
|
|
|
|
## Session, Memory, Dream
|
|
|
|
Session storage:
|
|
|
|
- stored under `~/.config/cc-slim/sessions/<workspace>/`
|
|
- message history in `.jsonl`
|
|
- metadata in `.meta.json`
|
|
|
|
Memory storage:
|
|
|
|
- stored under `~/.config/cc-slim/memory/<workspace>/MEMORY.md`
|
|
- structured sections:
|
|
- `User Memory`
|
|
- `Project Memory`
|
|
- `Constraints`
|
|
- `Consolidated Facts`
|
|
- `Scratch Notes`
|
|
|
|
`/remember`:
|
|
|
|
- appends raw notes into `Scratch Notes`
|
|
|
|
`/dream`:
|
|
|
|
- uses only the currently loaded session
|
|
- asks the model to extract durable information
|
|
- updates structured Memory sections
|
|
- keeps `Scratch Notes` intact
|
|
|
|
This is consolidation, not chat summary.
|
|
|
|
## Why This Project Is Intentionally Small
|
|
|
|
This repository is meant to demonstrate the core harness mechanics without hiding them behind infrastructure.
|
|
|
|
It intentionally does not include:
|
|
|
|
- sandbox
|
|
- because the project is about control flow and boundary handling, not process isolation
|
|
- sub-agent / coordinator orchestration
|
|
- because a single readable loop is easier to explain and verify
|
|
- vector DB / Mem0 backend
|
|
- because Memory here is file-based and explicit by design
|
|
- automatic background dream
|
|
- because manual consolidation makes the memory boundary easier to reason about
|
|
- complex skill runtime
|
|
- because workspace `SKILLS/*.md` is enough to show prompt layering without building a plugin platform
|
|
|
|
The result is smaller than production systems, but much easier to inspect, demo, and discuss.
|
|
|
|
## Testing
|
|
|
|
Run the current test suite:
|
|
|
|
```bash
|
|
uv run pytest -q
|
|
```
|
|
|
|
Current tests cover:
|
|
|
|
- config resolution
|
|
- tool primitives
|
|
- structured memory behavior
|
|
- dream updates
|
|
- prompt assembly order
|