🥥 Coconut - Persistent Memory & Task Orchestration for AI Agents

"Got it all here in my coconut!" — Claude

Overview

Coconut is a sophisticated command-line interface (CLI) system designed to provide persistent memory and task orchestration for AI agents, specifically Claude Code. It serves as a centralized hub for project management, status reporting, context synchronization, and development workflow orchestration.

Key Features

• 🧠 Persistent Memory: Maintains project state across AI sessions
• 🎖️ SITREP Generation: Military-style situation reports for status communication
• 📋 Task Orchestration: Structured task management with progress tracking
• 🔄 Context Synchronization: Automated collection and organization of project context
• 🚨 Recovery Systems: Crash recovery and session restoration
• 🌍 Environment Management: Development environment monitoring and validation
• 📊 Analytics: Project progress tracking and historical analysis

🤖 Compatibility

Built for Claude Code but works with any AI agent:

• ✅ Claude (all models - Code CLI, Opus, Sonnet, etc.)
• ✅ ChatGPT / GPT-4
• ✅ GitHub Copilot Chat
• ✅ Cursor AI
• ✅ Any AI that can read files

Coconut uses plain text files (Markdown, JSON, Bash) so any AI can understand it!

Quick Start

Installation

# Clone the repository
git clone https://github.com/jasonacurry/coconut.git

# Enter your project directory
cd your-project

# Run the installer
../coconut/install.sh

Basic Usage

# Run Coconut
./scripts/coconut.sh

# Main menu options:
# 1. View current tasks
# 2. Sync context (auto-generates SITREP)
# 3. Recover from crash
# 4. Check environment
# 5. Start new project
# 6. Archive completed tasks
# 7. Show stats
# 8. Check database state
# 9. Generate SITREP

Generate SITREP for AI Communication

# Option 1: Through Coconut menu
./scripts/coconut.sh
# Select option 9, then choose SITREP type

# Option 2: Direct command
./.claude/scripts/generate-sitrep.sh full

SITREP System

Coconut's signature feature is military-style situation reports optimized for AI agent communication:

• Standard SITREP: Progress since last report (auto-generated on sync)
• Today SITREP: Last 24 hours activity summary
• Full SITREP: Complete project overview for new stakeholders

Perfect for sharing project context with any AI assistant!

File Structure

your-project/
├── scripts/
│   └── coconut.sh              # Main CLI interface
├── .claude/                    # Coconut data directory
│   ├── scripts/                # Functional modules
│   │   ├── sync-context.sh     # Context synchronization
│   │   ├── generate-sitrep.sh  # SITREP generation
│   │   └── recover.sh          # Recovery systems
│   ├── tasks/                  # Task management
│   │   ├── current.txt         # Active tasks
│   │   └── archive/            # Completed projects
│   ├── context/                # Project context files
│   ├── sitreps/                # Situation reports
│   └── recovery/               # Recovery data
└── coconut.md                  # Complete documentation

Task Management

Coconut uses a structured task format for project tracking:

[ ] 001. Task description          # TODO
[►] 002. Task in progress         # IN PROGRESS  
[✓] 003. Completed task           # DONE

Integration

Works seamlessly with:

• Git: Branch tracking, commit history, status monitoring
• NPM: Package scripts, environment validation, build systems
• Databases: Schema monitoring, migration tracking
• Development Tools: Linting, formatting, deployment

Requirements

• Unix-like operating system (macOS, Linux)
• Bash shell (version 4.0+)
• Git installed and configured
• Node.js project with NPM (optional but recommended)

Documentation

See coconut.md for comprehensive documentation covering:

• Complete technical specifications
• Architecture and design patterns
• Installation and configuration
• Usage guides and best practices
• Troubleshooting and maintenance
• Extension and customization
• Security considerations
• Future roadmap

Quick Examples

Starting a New Project

./scripts/coconut.sh
# Select option 5: Start new project
# Copy prompt to your AI assistant
# Share your project requirements
# AI creates structured task list

Daily Workflow

# Morning: Sync and check tasks
./scripts/coconut.sh
# Option 2: Sync context
# Option 1: View current tasks

# Evening: Generate SITREP for handoff
# Option 9: Generate SITREP
# Copy to share with team or future AI sessions

Contributing

Contributions welcome! Please read CONTRIBUTING.md for guidelines on:

• Code standards and patterns
• Testing procedures
• Documentation requirements
• Pull request process

License

MIT License - Feel free to use, modify, and distribute!

Support

For issues, feature requests, or questions:

1. Check the troubleshooting section in coconut.md
2. Review existing issues
3. Open a new issue with detailed information

Acknowledgments

Created to solve the "AI amnesia" problem - because every AI agent deserves persistent memory!

Special thanks to Claude for the inspiring tagline: "Got it all here in my coconut!" 🥥

---

Coconut: Because every AI agent needs persistent memory! 🥥🧠