Project Kami 🗾

A comprehensive development environment for building and maintaining large-scale projects with Claude Code. Project Kami provides a complete, isolated Docker container that safely integrates your code, database, Claude Code with MCPs, and all necessary configurations - allowing Claude to operate with full file system access while maintaining security and consistency.

🎌 Core Principles

Project Kami operates on these fundamental principles:

🐳 Everything in One Container

• Complete isolation: Code, database, Claude Code, and all tools in a single Docker image
• Safe permissions: Run Claude with --dangerously-skip-permissions without risk
• Consistent environment: Every developer gets the exact same setup
• No host pollution: Your local machine stays clean

📝 Memory-Driven Development

• Persistent AI memory: Claude maintains comprehensive project understanding across sessions
• Requirements-first: All development traces back to documented requirements
• Living documentation: Architecture, roadmap, and changelog evolve with your project
• Context preservation: Never lose project knowledge between sessions

🔧 Integrated Tools & Configuration

• Claude Code: Latest version with full file system access
• MCP Servers: Pre-configured Model Context Protocol servers (PostgreSQL, Context7, n8n)
• Claude settings: Optimized configuration for large projects
• Cursor settings: Ready-to-use IDE configuration
• Development tools: Node.js, Python, PostgreSQL with pgvector, and more

🛡️ Security Through Isolation

• Container boundaries: Claude operates within Docker, not on your host
• Non-root user: Runs as devuser with controlled sudo access
• Volume mounts: Only specified directories are accessible
• Credential management: Secrets stay in the container

📌 Two Ways to Use Project Kami

Option 1: Starting a NEW Project (Empty Workspace)

Perfect when you want Claude to help you build from scratch with proper documentation structure in place from day one.

Option 2: Analyzing EXISTING Code (Import Your Project)

Ideal for establishing AI memory on an existing codebase - Claude will analyze your code and create comprehensive documentation.

🚀 Quick Start

1. Clone Project Kami

git clone <this-repo> my-project
cd my-project

2. Configure Your Project

cp env.template .env
# Edit .env with your project settings

3. Build & Start the Container

./setup.sh          # Build Docker image with all tools
./run-container.sh  # Start isolated development environment

Once inside the container, Claude Code has full access to:

• Your project files in /app (working-directory)
• PostgreSQL database (localhost:5432)
• All configured MCP servers
• Pre-installed development tools

4. Inside the Container

Option 1: NEW Project (Starting Fresh)

# First time only - authenticate Claude
claude auth login

# Create convenient alias for easier use
alias c='claude --dangerously-skip-permissions'

# Initialize the project structure with templates
/templates/agents/init-project.sh

# Start Claude
c

# IMPORTANT: First, work with Claude to define your requirements
# Choose one of these approaches:
# 1. "I want to build [your idea]. Let's define requirements together."
# 2. "Here's my design doc: [paste]. Help me create requirements.md"
# 3. "Quick start: I need a [type] app that [purpose]"

# After requirements.md is complete, run:
# /init-project-memory

# This will generate architecture, roadmap, and all documentation
# based on YOUR specific requirements

Option 2: EXISTING Project (Import & Analyze)

# First, copy your existing code to working-directory/
# Then inside the container:

# First time only - authenticate Claude
claude auth login

# Create convenient alias
alias c='claude --dangerously-skip-permissions'

# Initialize the memory structure
/templates/agents/init-project.sh

# Start Claude
c

# IMPORTANT: Copy the ENTIRE content from /CLAUDE_INITIALIZATION_PROMPT.md
# and paste it into Claude. This triggers the analysis process.
# Claude will:
# - Analyze your entire codebase
# - Detect frameworks, dependencies, and architecture
# - Create comprehensive documentation in memory/
# - Set up the AI agent memory system
# - Provide a summary of findings

🎯 What Project Kami Provides

For New Projects

• Requirements-First: Start by defining what you're building with Claude's help
• Smart Architecture: Technology recommendations based on YOUR specific needs
• Custom Roadmap: Phased implementation plan derived from requirements
• Best Practices: Templates include proven patterns from production projects
• Continuous Memory: Claude remembers your project context across sessions
• Living Documentation: Docs evolve automatically as you build

For Existing Projects

• Codebase Analysis: Claude examines your entire project structure
• Auto-Documentation: Generates architecture, requirements, and feature docs
• Pattern Detection: Identifies your coding standards and conventions
• Dependency Mapping: Documents all external integrations
• Technical Debt: Highlights potential issues and improvements

🔧 What's in the Container

Core Components

• Claude Code - Latest version with --dangerously-skip-permissions enabled safely
• PostgreSQL 15 - With pgvector extension for AI embeddings
• MCP Servers - Pre-configured and ready:
  • PostgreSQL MCP for database operations
  • Context7 MCP for up-to-date documentation
  • n8n MCP for workflow patterns
  • Supabase MCP (if configured)
• Development Runtimes:
  • Node.js 20 for frontend development
  • Python 3.11+ for backend development
  • Common tools (Git, curl, vim, build essentials)

Pre-installed Frameworks & Libraries

• Python: FastAPI, Django, Flask, SQLAlchemy, Celery, pytest
• Node.js: TypeScript, Vite, PM2, nodemon, React/Next.js tools
• Database: PostgreSQL client, pgvector, migration tools

Claude Code Features

• Full File System Access - Safe within container boundaries
• Persistent Memory - Project context maintained across sessions
• Custom Commands - Pre-built commands in .claude/commands/
• Project Templates - Best practices from production projects
• Automated Analysis - For existing codebases

📁 Project Structure

project-kami/
├── working-directory/     # Your project files (mounted to /app in container)
├── postgres-data/         # PostgreSQL data (persisted between sessions)
├── claude-config/         # Claude settings & auth (persisted)
├── templates/             # Project templates and configurations
│   ├── claude.md.template # AI agent constitution template
│   ├── memory/           # Documentation templates
│   ├── agents/           # Initialization scripts
│   └── .claude/          # Claude commands and configurations
├── Dockerfile            # Complete environment definition
├── setup.sh             # Build script
├── run-container.sh     # Launch script
├── env.template         # Environment configuration
└── CLAUDE_*.md          # Initialization guides

🛠️ How Project Kami Works

For New Projects

1. Run init script - Creates folder structure and template files
2. Start coding - Claude helps you build with templates as guides
3. Templates evolve - Documentation updates as you develop

For Existing Projects

When you paste the initialization prompt, Claude will:

• Detect project type, frameworks, and structure
• Analyze all code files and dependencies
• Map API endpoints and database schemas
• Infer business requirements from implementation
• Create comprehensive documentation

The Analysis Process (Existing Projects)

1. Project Discovery - Claude examines your entire codebase
2. Documentation Generation - Fills all template files with actual data
3. Architecture Mapping - Documents current system design
4. Feature Identification - Finds and documents key functionality
5. Memory Establishment - Creates persistent project context

What Gets Created

• memory/ directory with project-specific documentation
• claude.md file customized for your project
• Feature flow mappings for main functionality
• Architecture documentation from actual code
• Requirements inferred from implementation

📝 Memory System

The AI agent maintains structured memory in the memory/ directory:

Core Files

• claude.md - AI agent instructions and rules
• requirements.md - Business/functional requirements
• architecture.md - Technical architecture documentation
• roadmap.md - Prioritized development tasks
• changelog.md - Change history with timestamps
• feature-flows.md - Index of feature documentation

How Memory System Works

1. Start Container - Launch the development environment
2. Run Init Script - Creates memory/ structure and templates
3. For New Projects: Start coding immediately with Claude
4. For Existing Projects: Paste initialization prompt for analysis
5. Persistent Memory - All documentation maintained across sessions

The Memory Structure

memory/
├── architecture.md      # System design, APIs, database schema
├── requirements.md      # Business logic and features (source of truth)
├── roadmap.md          # Prioritized development tasks
├── changelog.md        # Timestamped history of changes
├── feature-flows.md    # Index of feature documentation
├── project_index.json  # Machine-readable project state
└── feature-flows/      # Detailed end-to-end feature docs
    └── [feature].md

🔧 Configuration

Environment Variables

Edit .env to customize:

# Project settings
PROJECT_NAME=my-awesome-app
DB_NAME=myapp_db
DB_USER=myapp_user

# Ports
FRONTEND_PORT=3000
BACKEND_PORT=5000

# Features
ENABLE_POSTGRES=true

Database Options

• PostgreSQL enabled by default
• Includes pgvector for AI/ML features
• Data persisted in postgres-data/
• Configure with environment variables

💡 Step-by-Step Usage Guide

🆕 Starting a NEW Project

1. Setup & Launch

   git clone <this-repo> my-new-project
   cd my-new-project
   cp env.template .env
   # Edit .env with your project name
   ./setup.sh && ./run-container.sh

2. Inside Container

   claude auth login  # First time only
   alias c='claude --dangerously-skip-permissions'
   /templates/agents/init-project.sh
   c

3. Define Requirements First

   • Work with Claude to create memory/requirements.md
   • This is the MOST IMPORTANT step - don't skip it!
   • Options: guided discussion, from existing docs, or quick start
   • See /CLAUDE_NEW_PROJECT_INIT.md for detailed approaches

4. Initialize Project Memory

   • Once requirements are defined, run: /init-project-memory
   • Claude analyzes requirements and generates:
     • Architecture design based on your needs
     • Phased roadmap for implementation
     • All documentation templates filled with project-specific content

5. Start Building

   • Begin with the first roadmap item
   • Claude has full context from requirements
   • All suggestions align with your project goals
   • Documentation updates automatically as you work

📥 Importing an EXISTING Project

1. Prepare Your Code

   git clone <this-repo> my-project-with-ai
   cd my-project-with-ai
   cp -r /path/to/your/existing/code/* working-directory/
   cp env.template .env
   # Edit .env with your project name

2. Launch & Initialize

   ./setup.sh && ./run-container.sh
   # Inside container:
   claude auth login  # First time only
   alias c='claude --dangerously-skip-permissions'
   /templates/agents/init-project.sh
   c

3. Trigger Analysis

   • Open /CLAUDE_INITIALIZATION_PROMPT.md in another terminal
   • Copy the ENTIRE content
   • Paste into Claude
   • Wait for analysis (usually 1-3 minutes depending on project size)
   • Claude will create complete documentation in memory/

🔄 Continuous Development

Once initialized (either way), Claude maintains persistent memory:

• Just run c to start Claude
• All project context is preserved
• Documentation updates automatically
• Use commands like:
  • "Update the changelog"
  • "What's next on the roadmap?"
  • "Document the authentication flow"

🎯 Key Differences

Aspect	New Project	Existing Project
Starting Point	Empty workspace	Your codebase
Init Script	Creates templates	Creates templates
Next Step	Define requirements	Paste analysis prompt
Claude's Role	Helps plan, then builds	Analyzes then assists
Documentation	Created from requirements	Generated from code
Time to Start	~5-10 min planning	~1-3 min analysis
First Output	Requirements & roadmap	Complete documentation

🚦 Workflow Example

1. Start Container

   ./run-container.sh

2. Authenticate Claude (first time only)

   claude auth login
   alias c='claude --dangerously-skip-permissions'

3. Start Claude

   c

4. Initialize Project Memory

   • Open /CLAUDE_INITIALIZATION_PROMPT.md
   • Copy the entire prompt
   • Paste into Claude
   • Claude analyzes your project and creates all documentation

5. Develop with AI Assistance

   • Claude now has full project context
   • Memory persists across sessions
   • Documentation updates as you work

🔒 Security Notes

• Development environment only
• Runs as devuser with sudo privileges (not root)
• Default passwords in .env
• Never commit real credentials
• PostgreSQL runs as superuser in dev

🏯 Why Project Kami?

Project Kami (神) - meaning "spirit" or "divine" in Japanese - represents the philosophy of bringing life and intelligence to your development environment.

Key Benefits:

• Scale with Confidence: Manage large codebases with persistent AI memory
• Safe Experimentation: Claude has full access within container boundaries
• Team Consistency: Everyone uses the same environment and tools
• Production Patterns: Based on real-world project best practices
• Zero Setup Time: Everything pre-configured and ready to use

Proven Approach:

This approach has been battle-tested on production projects including:

• Multi-service SaaS applications
• AI-powered platforms
• Full-stack web applications
• Complex system integrations

🤝 Contributing

Project Kami is designed to evolve with the community. Contributions welcome:

• Additional MCP server integrations
• More language/framework support
• Enhanced Claude commands
• Template improvements
• Documentation enhancements
• Security hardening

📚 Advanced Features

Custom Agents

Add your own analysis agents in templates/agents/:

• Language-specific analyzers
• Framework detectors
• Custom documentation generators

Template Customization

Modify templates in templates/memory/:

• Adjust documentation format
• Add project-specific sections
• Customize for your workflow

Persistent Volumes

Three volumes ensure nothing is lost:

• working-directory/ - Your code (owned by devuser)
• postgres-data/ - Database
• claude-config/ - Claude authentication (mounted to /home/devuser/.claude)

MCP Server Configuration

Project Kami comes with pre-configured MCP servers:

• PostgreSQL MCP - Direct database operations within Claude
• Context7 MCP - Access to up-to-date library documentation
• n8n MCP - Workflow automation patterns
• Supabase MCP - If you're using Supabase (configure API key)

All MCP servers are configured in Claude's settings and ready to use.

🐛 Troubleshooting

Container Won't Start

• Check Docker is running
• Ensure ports aren't in use (especially port 5005 - may conflict with macOS AirPlay)
• Review docker logs
• If port conflict, change BACKEND_PORT in .env file

PostgreSQL Issues

• Check .env configuration
• Verify postgres-data/ permissions
• Try removing postgres-data/ for fresh start

Claude Authentication

• Run claude auth login inside container
• Check claude-config/ is mounted
• Ensure internet connectivity
• Use the alias: alias c='claude --dangerously-skip-permissions'

Analysis Not Working

• Ensure you copied the ENTIRE prompt from /CLAUDE_INITIALIZATION_PROMPT.md
• Check that your code is in working-directory/
• Give Claude time to analyze (larger projects take longer)
• Check for any error messages in Claude's response

📖 Learn More

• Claude Code Documentation
• Docker Documentation
• PostgreSQL Documentation

🌟 Getting Started

Ready to experience the power of Project Kami?

git clone https://github.com/[your-repo]/project-kami.git
cd project-kami
./setup.sh && ./run-container.sh

Welcome to a new era of AI-assisted development where Claude Code can safely operate at full capacity, your environment stays consistent, and your project knowledge persists forever.

---

Project Kami - Bringing divine intelligence to your development workflow 🗾