207 lines
6.5 KiB
Markdown
207 lines
6.5 KiB
Markdown
# Loki Mode - Conversation Context Export
|
|
|
|
**Date:** 2025-12-28
|
|
**Version:** 2.5.0
|
|
**Repository:** https://github.com/asklokesh/loki-mode
|
|
|
|
---
|
|
|
|
## Project Overview
|
|
|
|
**Loki Mode** is a Claude Code skill that provides a multi-agent autonomous startup system. It dynamically orchestrates specialized agents across 6 swarms to take a PRD from idea to fully deployed product. It spawns only the agents needed - from a few for simple projects to 100+ for complex startups.
|
|
|
|
### Key Features
|
|
- 37 specialized agent types across 6 swarms (Engineering, Operations, Business, Data, Product, Growth)
|
|
- Dynamic agent scaling based on project complexity
|
|
- Task tool for subagent dispatch with fresh context
|
|
- Distributed task queue (pending, in-progress, completed, failed, dead-letter)
|
|
- Circuit breakers for per-agent failure handling
|
|
- Timeout/stuck agent detection with heartbeat monitoring
|
|
- State recovery via checkpoints in `.loki/state/`
|
|
- Autonomous execution with auto-resume on rate limits
|
|
|
|
---
|
|
|
|
## File Structure
|
|
|
|
```
|
|
loki-mode/
|
|
├── SKILL.md # The main skill file (YAML frontmatter required)
|
|
├── VERSION # Current version: 2.4.0
|
|
├── CHANGELOG.md # Full version history
|
|
├── README.md # Main documentation
|
|
├── references/
|
|
│ ├── agents.md # 37 agent type definitions
|
|
│ ├── deployment.md # Cloud deployment guides
|
|
│ └── business-ops.md # Business operation workflows
|
|
├── examples/
|
|
│ ├── simple-todo-app.md # Simple PRD for testing
|
|
│ ├── api-only.md # Backend-only PRD
|
|
│ ├── static-landing-page.md # Frontend/marketing PRD
|
|
│ └── full-stack-demo.md # Complete bookmark manager PRD
|
|
├── tests/
|
|
│ ├── run-all-tests.sh # Main test runner (53 tests)
|
|
│ ├── test-bootstrap.sh # 8 tests
|
|
│ ├── test-task-queue.sh # 8 tests
|
|
│ ├── test-circuit-breaker.sh # 8 tests
|
|
│ ├── test-agent-timeout.sh # 9 tests
|
|
│ ├── test-state-recovery.sh # 8 tests
|
|
│ └── test-wrapper.sh # 12 tests
|
|
├── scripts/
|
|
│ ├── loki-wrapper.sh # Legacy wrapper (deprecated)
|
|
│ └── export-to-vibe-kanban.sh # Optional Vibe Kanban export
|
|
├── integrations/
|
|
│ └── vibe-kanban.md # Vibe Kanban integration guide
|
|
├── autonomy/
|
|
│ ├── run.sh # ⭐ MAIN ENTRY POINT - handles everything
|
|
│ └── README.md # Autonomy documentation
|
|
└── .github/workflows/
|
|
└── release.yml # GitHub Actions for releases
|
|
```
|
|
|
|
---
|
|
|
|
## How to Use
|
|
|
|
### Quick Start (Recommended)
|
|
```bash
|
|
./autonomy/run.sh ./docs/requirements.md
|
|
```
|
|
|
|
### What run.sh Does
|
|
1. Checks prerequisites (Claude CLI, Python, Git, curl)
|
|
2. Verifies skill installation
|
|
3. Initializes `.loki/` directory
|
|
4. Starts status monitor (updates `.loki/STATUS.txt` every 5s)
|
|
5. Runs Claude Code with live output
|
|
6. Auto-resumes on rate limits with exponential backoff
|
|
7. Continues until completion or max retries
|
|
|
|
### Monitor Progress
|
|
```bash
|
|
# In another terminal
|
|
watch -n 2 cat .loki/STATUS.txt
|
|
```
|
|
|
|
---
|
|
|
|
## Key Technical Details
|
|
|
|
### Claude Code Invocation
|
|
The autonomy runner pipes the prompt through stdin for live output:
|
|
```bash
|
|
echo "$prompt" | claude --dangerously-skip-permissions
|
|
```
|
|
|
|
**Important:** Using `-p` flag doesn't stream output properly. Piping through stdin shows interactive output.
|
|
|
|
### State Files
|
|
- `.loki/state/orchestrator.json` - Current phase, metrics
|
|
- `.loki/autonomy-state.json` - Retry count, status, PID
|
|
- `.loki/queue/*.json` - Task queues
|
|
- `.loki/STATUS.txt` - Human-readable status (updated every 5s)
|
|
- `.loki/logs/*.log` - Execution logs
|
|
|
|
### Environment Variables
|
|
| Variable | Default | Description |
|
|
|----------|---------|-------------|
|
|
| `LOKI_MAX_RETRIES` | 50 | Max retry attempts |
|
|
| `LOKI_BASE_WAIT` | 60 | Base wait time (seconds) |
|
|
| `LOKI_MAX_WAIT` | 3600 | Max wait time (1 hour) |
|
|
| `LOKI_SKIP_PREREQS` | false | Skip prerequisite checks |
|
|
|
|
---
|
|
|
|
## Version History Summary
|
|
|
|
| Version | Key Changes |
|
|
|---------|-------------|
|
|
| 2.5.0 | Real streaming output (stream-json), Web dashboard with Anthropic design |
|
|
| 2.4.0 | Live output fix (stdin pipe), STATUS.txt monitor |
|
|
| 2.3.0 | Unified autonomy runner (`autonomy/run.sh`) |
|
|
| 2.2.0 | Vibe Kanban integration |
|
|
| 2.1.0 | Autonomous wrapper with auto-resume |
|
|
| 2.0.x | Test suite, macOS compatibility, release workflow |
|
|
| 1.x.x | Initial skill with agents, deployment guides |
|
|
|
|
---
|
|
|
|
## Known Issues & Solutions
|
|
|
|
### 1. "Blank output when running autonomously"
|
|
**Cause:** Using `-p` flag doesn't stream output
|
|
**Solution:** Use stdin pipe: `echo "$prompt" | claude --dangerously-skip-permissions`
|
|
|
|
### 2. "Vibe Kanban not showing tasks"
|
|
**Cause:** Vibe Kanban is UI-driven, doesn't read JSON files automatically
|
|
**Solution:** Use `.loki/STATUS.txt` for monitoring, or run Vibe Kanban separately
|
|
|
|
### 3. "timeout command not found on macOS"
|
|
**Cause:** macOS doesn't have GNU coreutils
|
|
**Solution:** Perl-based fallback in test scripts
|
|
|
|
### 4. "TTY raw mode error"
|
|
**Cause:** Running Claude in non-interactive mode
|
|
**Solution:** Latest commit (008ed86) adds `--no-input` flag
|
|
|
|
---
|
|
|
|
## Git Configuration
|
|
|
|
**Committer:** asklokesh (never use Claude as co-author)
|
|
|
|
**Commit format:**
|
|
```
|
|
Short description (vX.X.X)
|
|
|
|
Detailed bullet points of changes
|
|
```
|
|
|
|
---
|
|
|
|
## Test Suite
|
|
|
|
Run all tests:
|
|
```bash
|
|
./tests/run-all-tests.sh
|
|
```
|
|
|
|
53 tests across 6 test suites - all should pass.
|
|
|
|
---
|
|
|
|
## Pending/Future Work
|
|
|
|
1. **Vibe Kanban proper integration** - Vibe Kanban doesn't read files, would need API integration
|
|
2. **Better live output** - Current stdin pipe works but may have edge cases
|
|
3. **Task visualization** - Could add a simple TUI for task monitoring
|
|
|
|
---
|
|
|
|
## Important Files to Read First
|
|
|
|
When starting a new session, read these files:
|
|
1. `SKILL.md` - The actual skill instructions
|
|
2. `autonomy/run.sh` - Main entry point
|
|
3. `VERSION` and `CHANGELOG.md` - Current state
|
|
4. This file (`CONTEXT-EXPORT.md`) - Full context
|
|
|
|
---
|
|
|
|
## User Preferences
|
|
|
|
- Always use `asklokesh` as committer
|
|
- Never use Claude as co-author
|
|
- Keep skill files clean, autonomy separate
|
|
- Test before pushing
|
|
- Live output is important - user wants to see what's happening
|
|
|
|
---
|
|
|
|
## Last Known State
|
|
|
|
- **Version:** 2.5.0
|
|
- **Latest Commit:** (pending push)
|
|
- **Tests:** All 53 passing
|
|
- **Features Added:** Real-time streaming output via stream-json, web dashboard with Anthropic design
|