# 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