Clawie mascot Clawie
GitHub Start
Getting Started

Clawie Docs

Open Clawie from the Rust workspace, configure your model if prompted, and start with a small coding request in the terminal.

Clawie is a terminal coding helper. You type what you want, Clawie answers, explores files, explains code, and helps make changes when you ask.

cd /Users/horatiubudai/ceo/ShrimpAI/Clawie-full/Clawie
./clawie setup
./clawie

What Clawie is

  • a coding assistant that runs in your terminal
  • a workspace with a Rust CLI and a Python side folder
  • a helper for reading files, explaining code, editing code, and fixing bugs
  • a simple place to ask coding questions while staying inside your project

Choose your path

Start with the Rust CLI when you want to talk to Clawie. Use the Python workspace when you need supporting commands or extra workspace logic.

Rust CLI

Main terminal app. This is the best place to start for normal Clawie usage.

Python workspace

Supporting workspace that sits next to the CLI for helper logic and commands.

Start Clawie

If you already have the project on your computer, start inside the unified `Clawie-full/Clawie` package directory.

1

Open the Clawie folder

Find `Clawie-full`, then open the `Clawie` folder inside it.

2

Run the setup wizard

Initialize models, base URLs, and API key configuration: ./clawie setup

3

Start the agent REPL

Launch the stateful CLI agent command session: ./clawie

4

Interact in normal mode

Ask a request like "explain this workspace" or use mapping/git utilities.

How to use it

Keep your first request small. Read what Clawie says before asking it to change important files.

1

Ask one easy thing first

Good examples: "show me the files", "explain this code", or "help me change the navbar".

2

Read the answer

Clawie usually explains what it is doing before it changes anything important.

3

Use slash commands

Use `/help` for guidance and `/model` when you want to change models.

4

Ask for bigger work

After a simple task works, ask Clawie to edit files, inspect code, or help fix bugs.

Good first commands

./clawie setup     # Configure workspace settings
./clawie           # Launch CLI REPL session
/map               # Output repository file structure map
/lean-review       # Review diffs for over-engineering

Lazy Senior Dev Mode (Lean Mode)

Clawie enforces a strict Lean Ladder check list to ensure over-engineering is avoided: checks if a feature needs to exist, is already in the codebase, can be solved by stdlib, native APIs, or an existing dependency before writing minimum code.

/lean [lite|full|ultra|off] # Switch or check the active lean mode
/lean-review                # Review current diffs for over-engineering
/lean-audit                 # Scan repository for over-engineering
/lean-debt                  # Harvest simplification comments into a ledger
/lean-gain                  # Show performance benchmark impact metrics

Git Integration & Repository Mapping

Analyze repository structure and manage git commits natively within the Clawie REPL session.

/map # Rank files and extract symbols to navigate large codebases
/commit # Preflights changes, auto-generates commit messages, and commits
/undo # Reverts last commit as a soft reset, preserving changes

RAG Indexer & Sync Pipelines

Generate SQLite-backed vector semantic maps of your workspace and run parity sync checks between Rust and Python modules.

# Ingest files into workspace RAG service
cargo run -p claw-rag-service -- ingest --workspace .

# Serve the RAG API and search interface
cargo run -p claw-rag-service -- serve

# Run synchronicity pipeline check script
./scripts/check_rust_python_sync.py

Clawie Web UI & Pixel Agents Dashboard

Clawie includes a full-featured graphical interface with advanced developer tools.

  • WebSocket Live Log Streaming: Watch process lifecycle events, command elapsed times, and logs stream live.
  • Side-by-Side Visual Diffing: Compare original file content against agent improvements side-by-side.
  • Pixel Agents Visualizer: A gamified visual dashboard showing draggable pixel-art characters representing active CLI agent runtimes.
/webui # Open the Web UI from the REPL session
./clawie --webui # Open the Web UI from terminal

Long Sessions & Budget Tuning

Clawie's execution runtime is pre-configured with default values optimized to support longer coding sessions:

  • max_turns: 64 – Maximum execution loops per request.
  • max_budget_tokens: 12000 – Limits model token consumption budget.
  • compact_after_turns: 48 – Compacts runtime context window automatically to control token depth.

You can customize these properties inside your terminal session by exporting environment variables before starting Clawie:

export CLAWIE_MAX_TURNS=120
export CLAWIE_MAX_BUDGET_TOKENS=30000
export CLAWIE_COMPACT_AFTER_TURNS=80
./clawie

Workspace & Repo Architecture

Clawie packages CLI execution runtimes and mirror files in a unified repository, keeping the system shareable and runnable from a single folder.

Clawie/
├── clawie                  # Packaged execution runner script
├── rust-clawie/            # Main Rust CLI and LLM gateway codebase
├── python-clawie/          # Supporting Python mirrored modules
└── scripts/                # Synchronicity and sync check pipelines

Choose your workspace focus area depending on what you are developing:

  • Use rust-clawie for primary terminal CLI improvements, parser actions, and gateway features.
  • Use python-clawie for background mirrors, tests, and supporting script integrations.

If you get stuck

  • If Clawie asks for a key or provider, follow the setup questions on screen before trying again.
  • If nothing starts, make sure you are inside `rust-clawie/rust` before running the command.
  • If you feel lost, type `/help` to see what Clawie can do.
  • Start with one tiny request. Small steps make everything easier.