Skip to content

Installation

Step-by-step guide to install coding on your system.

Prerequisites

Before installing, ensure you have these tools:

# Install prerequisites
brew install git node jq tmux

# Install Docker Desktop
brew install --cask docker

# Install prerequisites
sudo apt update && sudo apt install -y git nodejs npm jq tmux

# Install Docker
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER  # Log out and back in
  1. Install WSL2
  2. Install Docker Desktop
  3. In WSL2: 
    sudo apt update && sudo apt install -y git nodejs npm jq tmux

Version Requirements

Tool Minimum Version Check Command
Node.js 18+ node --version
Git 2.0+ git --version
tmux 3.0+ tmux -V
Docker 20+ docker --version
jq 1.6+ jq --version

Docker Installation

Coding runs in Docker. All services (MCP servers, databases, dashboards) run as containers; only the Claude/Copilot CLI runs natively on the host.

Docker Architecture

Step 1: Clone Repository

git clone --recurse-submodules https://github.com/fwornle/coding ~/Agentic/coding
cd ~/Agentic/coding

Existing Clone?

If you already cloned without submodules: 

git submodule update --init --recursive

Step 2: Run Installer

./install.sh

The installer will:

  1. Verify Docker is installed and running
  2. Build Docker containers
  3. Configure Claude MCP servers for SSE/HTTP communication
  4. Set up Claude hooks (LSL, constraints)
  5. Initialize knowledge store
  6. Add coding and vkb commands to your PATH

Non-Intrusive Installation

The installer prompts before any system changes and creates timestamped backups of your shell configuration. Use --skip-all to decline all system-level changes.

Step 3: Reload Shell

source ~/.bashrc  # or ~/.zshrc for Zsh

Step 4: Verify Installation

coding --health

Health Check

You should see all services reporting healthy (green).

Step 5: Start Coding

coding

Coding Startup

What Gets Installed

Component Location Purpose
coding command ~/Agentic/coding/bin/ Launch Claude with all integrations
vkb command ~/Agentic/coding/bin/ View Knowledge Base
ukb command ~/Agentic/coding/bin/ Update Knowledge Base
MCP Servers Docker Semantic Analysis, Constraints, etc.
Claude Hooks ~/.claude/settings.json LSL monitoring, constraint checks
Knowledge Store .data/knowledge-graph/ Graph database
Session Logs .specstory/history/ LSL files

Configuration Files Created

File Purpose
~/.claude/settings.json Claude hooks configuration
.env API keys and settings
.env.ports Port configuration

Troubleshooting Installation

Docker Not Found

# Verify Docker is installed
docker --version

# Verify Docker daemon is running
docker info

# On macOS, ensure Docker Desktop is running

Permission Denied

# Fix Docker socket permissions (Linux)
sudo usermod -aG docker $USER
# Log out and back in

# Fix directory permissions
chmod -R 755 ~/Agentic/coding

Submodules Missing

cd ~/Agentic/coding
git submodule update --init --recursive

Port Conflicts

# Check what's using a port
lsof -i :8080

# Change ports in .env.ports
cat .env.ports

Reinstallation

To completely reinstall:

cd ~/Agentic/coding

# Stop all services
docker compose -f docker/docker-compose.yml down 2>/dev/null
pkill -f "coding"

# Clean state (preserves knowledge base)
rm -f .transition-in-progress

# Reinstall
./install.sh

Next Steps