156 lines
3.7 KiB
Markdown
156 lines
3.7 KiB
Markdown
# Claude Loop Project
|
|
|
|
A Docker-based automated task execution system using Claude AI to process and complete tasks defined in `.claude/plan.md`.
|
|
|
|
## Demo
|
|
|
|
|
|
|
|
## 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
|