Run Claude agents overnight to build your projects autonomously.
Built by Travis Eric as part of the Teneo ecosystem. Enhanced with insights from the AI-first development community including Geoffrey Huntley and Steve Yegge.
This is the open-source foundation. My production system runs 40+ specialized agent types with intelligent routing, multi-account failover, production readiness pipelines, and browser QA — across a full project portfolio. Learn more at traviseric.com.
# 1. Clone this repo
git clone https://github.com/Traviseric/teneo-agent.git
cd teneo-agent
# 2. Login to Claude CLI
claude login
# 3. Choose your runner:# Create task file
cp TASKS.md.example TASKS.md
# Edit with your tasks
# Run
python teneo_agent.py start --project /path/to/project --continuous# Create PROMPT.md in your project with intent + tasks
# Then run
python ralph_runner.py --project /path/to/project --max 10| Runner | Pattern | Best For |
|---|---|---|
teneo_agent.py |
Task relay | Checkbox tasks, parallel workers |
ralph_runner.py |
Ralph Loop | Fresh context, PROMPT.md driven |
Relay Runner (my pattern): Workers claim tasks from TASKS.md, execute, mark complete. Good for parallel work.
Ralph Runner (Geoff Huntley's pattern): Each iteration reads PROMPT.md with fresh context. No memory accumulation. while :; do cat PROMPT.md | agent; done
Try both, see what works for your workflow. Feedback welcome!
┌─────────────────────────────────────────────────────────┐
│ TENEO AGENT │
│ │
│ TASKS.md ──► Agent reads task │
│ │ │
│ ▼ │
│ Spawn Claude worker in terminal │
│ │ │
│ ▼ │
│ Worker executes task autonomously │
│ │ │
│ ▼ │
│ Worker writes HANDOFF.md when done │
│ │ │
│ ▼ │
│ Git checkpoint (commit + push) │
│ │ │
│ ▼ │
│ Loop: Next task until done │
└─────────────────────────────────────────────────────────┘
- Python 3.8+
- Claude CLI -
npm install -g @anthropic-ai/claude-code - Git - for checkpoints
- Windows Terminal (Windows) or Terminal.app (macOS) or gnome-terminal (Linux)
# Run single round (1 task)
python teneo_agent.py start --project ./my-project
# Run continuously until all tasks done
python teneo_agent.py start --project ./my-project --continuous
# Run with 2 parallel workers
python teneo_agent.py start --project ./my-project --lanes 2 --continuous
# Check status
python teneo_agent.py statusCreate TASKS.md with checkbox-format tasks:
# Project Tasks
## Phase 1: Setup
- [ ] Initialize project with Next.js and TypeScript
- [ ] Add Tailwind CSS configuration
- [ ] Create basic folder structure
## Phase 2: Features
- [ ] Create login page with email/password form
- [ ] Add user dashboard page
- [ ] Implement API routes for authentication
## Phase 3: Polish
- [ ] Add loading states to all buttons
- [ ] Write unit tests for auth functions
- [ ] Update README with setup instructionsWorkers will:
- Pick up the first incomplete task (
- [ ]) - Execute it in your project
- Mark it complete (
- [x]) when done - Write a handoff for the next worker
teneo-agent/
├── teneo_agent.py # Main script
├── TASKS.md # Your task list (create this)
├── agent_runs/ # Worker output (auto-created)
│ └── round_1_lane_1/
│ ├── WORKER.md # Worker instructions
│ ├── LOG.md # Progress log
│ └── HANDOFF.md # Completion handoff
└── README.md
Teneo Agent implements patterns I developed through months of overnight agent runs:
- File-based coordination - TASKS.md is the source of truth
- Worker isolation - each worker gets a clean context
- Checkpoint safety - git commits protect your work
- Handoff continuity - workers pass context to the next
After building the core system, I studied work from Huntley and Yegge:
- Fresh context principle (Huntley) - reinforced my worker isolation approach
- Landing the Plane (Yegge) - formalized my checkpoint discipline
# Optional - Claude CLI handles auth, but you can set this
ANTHROPIC_API_KEY=your_key_here| Option | Default | Description |
|---|---|---|
--project, -p |
. |
Path to your project |
--lanes, -l |
1 |
Parallel workers |
--continuous, -c |
false |
Run until tasks done |
--max-rounds, -m |
50 |
Max rounds to run |
-
Write clear tasks - "Add login form with email validation" not "do auth stuff"
-
One thing per task - break big features into smaller tasks
-
Include acceptance criteria - "Add tests that verify login works"
-
Order matters - put dependencies first (setup before features)
-
Run during low-stakes time - overnight, when you can review in the morning
Before running overnight agents, optimize your project structure:
# 1. Clone teneo-agent
git clone https://github.com/Traviseric/teneo-agent.git
# 2. Open Claude Code in YOUR project
cd /path/to/your/project
claude
# 3. Run the audit (paste this prompt)Read the best practices at [path-to-teneo-agent]/BEST_PRACTICES.md
Then audit THIS project against those practices and give me a scorecard.
Claude will analyze your CLAUDE.md, project structure, documentation, and testing setup - then give you specific recommendations.
Full guide: docs/AUDIT_YOUR_PROJECT.md
| Guide | What You'll Learn |
|---|---|
| Audit Your Project | Run Claude to score and improve your project |
| Best Practices | 10 principles for agent success |
| Doc Organization | Structure docs so agents navigate efficiently |
| MCP Optimization | Fix MCP token bloat |
| Getting Started | First-time setup, CLAUDE.md template |
| Task Template | Example task file format |
Join 100+ builders running AI agents overnight:
AI Builders Lab on Skool (Free)
- Share your overnight run results
- Get feedback on your TASKS.md
- Learn from others' workflows
- Weekly tips and patterns
- Direct access to Travis
Free Resources:
- AI Builders Lab - Free community for overnight agent builders
- AI-First Fundamentals - Free course, 37 lessons on engineering principles
Go Deeper:
- Complete AI Development System - Full 27 principles + enhanced agent + all guides ($197)
- AI Orchestra Method - Scale to 18+ parallel instances ($97)
MIT License - see LICENSE
Travis Eric - traviseric.com
Built by Travis Eric. Enhanced with insights from the AI-first development community.
Join the community - Share your overnight runs, learn from others.