cc-slim/README.md

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

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:

uv run cc-slim

Run from elsewhere but target a workspace explicitly:

uv run cc-slim --workspace E:\04test

Single-shot prompt:

uv run cc-slim "what does this repo do?"

List history for the current workspace:

uv run cc-slim --history

Resume a prior session:

uv run cc-slim --resume 1

Skip confirmation for high-risk tools:

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

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:

uv run pytest -q

Current tests cover:

• config resolution
• tool primitives
• structured memory behavior
• dream updates
• prompt assembly order