initial

README.md

@@ -0,0 +1,155 @@
+# Claude Loop Project
+
+A Docker-based automated task execution system using Claude AI to process and complete tasks defined in `.claude/plan.md`.
+
+## Demo
+
+![Demo](./demo.gif)
+
+## Overview
+
+This project provides two main scripts for interacting with Claude AI in a sandboxed Docker environment:
+
+- **`ccl`** (Claude Code Loop) - Runs an automated loop that processes tasks from `.claude/plan.md`
+- **`ccsb`** (Claude Code Sandbox) - Executes single Claude commands with full tool access
+
+## Prerequisites
+
+1. **Docker**
+2. **Claude CLI**
+3. **Gemini CLI** (optional) - For documentation queries / gemini-cli mcp (https://github.com/jamubc/gemini-mcp-tool)
+4. **User Home Directory** - Scripts must be run from within your home directory for security
+5. **Linux** (or WSL) - with user 1000:1000
+
+## Security Warning
+
+- While rootless docker is very safe, it still has access to the internet and you local network and can possibly cause (limited) havoc.
+
+## Setup
+
+### 1. Build the Docker Image
+
+```bash
+docker compose build
+```
+
+### 2. Configure Claude CLI
+
+Ensure you have:
+- `~/.claude.json` - Claude CLI configuration
+- `~/.claude/` - Claude settings directory
+
+### 3. Configure Gemini CLI (Optional)
+
+If using gemini-cli for documentation queries:
+- `~/.gemini/` - Gemini settings
+- `GEMINI_API_KEY` environment variable
+
+### 4. symlink (or move) to /bin
+```bash
+ln -s ccl /bin/ccl
+ln -s ccsb /bin/ccsb
+```
+
+## Usage
+
+### CCL (Claude Code Loop)
+
+Automatically processes tasks defined in `.claude/plan.md`:
+
+```bash
+ccl
+```
+
+**Features:**
+- Reads tasks from `.claude/plan.md`
+- Updates task statuses: `(Not Started)` → `(In Progress)` → `(Completed)/(Aborted)`
+- Continues until all tasks show `(Completed)`
+- Creates `/tmp/plan_complete` when finished
+- Pretty formatted output with progress tracking
+
+**Task Status Format:**
+```markdown
+- (Status) Task description
+```
+
+Status options: `Not Started | In Progress | Aborted | Completed`
+
+### CCSB (Claude Code Sandbox)
+
+Execute claude in a sandbox with all permissions.
+
+```bash
+ccsb
+```
+
+## Plan File Structure
+
+The `.claude/plan.md` file defines tasks to be executed:
+
+```markdown
+# Project Name
+
+## IMPORTANT (instructions for Claude when in ccl mode, does not apply to ccsb)
+- Project-specific guidelines
+- Tool preferences
+- Constraints
+
+## PLAN
+
+### Section 1
+- Task 1 description
+- Task 2 description
+
+### Section 2  
+- Task 3 description
+
+## POST TASK TASKS
+- Cleanup tasks
+- Final commits
+- Documentation updates
+```
+
+## Tips
+
+- You can ask ccsb to run claude-loop
+- You can ask claude to keep a work-log such as:
+```markdown
+- Append work to .claude/work-log.md, never read entire file into context with format $(date): <task>\n\n
+- tail work-log.md before starting
+- Focus on words with !! for accuracy
+- Look for (Changes Needed) and view all the changes requested below
+```
+- Changes Needed example
+```markdown
+### Some Tasks Topic
+- (Completed) Task1
+- (Changes Needed) Original task to build a snowman
+  - You built a snowman without a head, add a head
+```
+
+## Security Features
+
+- **Home Directory Restriction**: Scripts only run from within user home directory
+- **Docker Isolation**: All Claude operations run in isolated container
+- **Non-root Execution**: Container runs as user `1000:1000`
+- **Limited File Access**: Only mounted directories are accessible
+
+## Troubleshooting
+
+### Common Issues
+
+1. **"Must be run from within user home directory"**
+   - Ensure you're running the script from a subdirectory of `$HOME`
+
+2. **Docker permission errors**
+   - Check Docker is running and user has permissions
+   - Verify volume mounts point to existing directories
+
+3. **Claude CLI not configured**
+   - Run `claude` to set up claude
+   - Ensure `~/.claude.json` exists
+
+## License
+
+MIT