Installation¶

Install¶

git clone --recurse-submodules https://github.com/fwornle/coding ~/Agentic/coding
cd ~/Agentic/coding && ./install.sh
source ~/.zshrc          # or ~/.bashrc
cd ~/my-project && coding

--recurse-submodules is not optional — several integrations are submodules and the install fails confusingly without them.

The two questions¶

1 — agent scope. Enter (n) keeps your global agent configs untouched: only sessions started through coding are logged and get knowledge injected.

2 — tier. Each tier is a superset of the one before. Enter installs harness.

Change it any time: coding-features profile <tier>, or Dashboard → Features.

The first launch in each repo¶

With a learning tier, the first coding in a repo asks where its learned data goes — Enter creates a private <repo>-history, a teammate's URL shares theirs, skip keeps it local. See Per-Repo Tenancy.

What you need¶

Node.js 22 LTS or newer, plus git, jq and tmux. Docker (running, not just installed) only for learning and up.

brew install git node jq tmux && brew install --cask docker

sudo apt update && sudo apt install -y git nodejs npm jq tmux
curl -fsSL https://get.docker.com | sh

On Windows, install inside WSL (with systemd enabled in /etc/wsl.conf); there is no native Windows installer.

What it does to your machine¶

Prompts before any system-level change, backs up your shell config with a timestamp, and supports --skip-all to decline every system change. Its own state stays in the checkout.

If it fails¶

Most first-run failures are Docker not running, or a shell not reloaded since the install. Verify & Repair works through the rest.

Before you start¶

Installing¶

git clone --recurse-submodules https://github.com/fwornle/coding ~/Agentic/coding
cd ~/Agentic/coding && ./install.sh
source ~/.zshrc

The services run as Docker containers with only the agent CLI native on the host, talking to them through stdio proxies. That is what keeps the install contained and makes removal a matter of stopping containers.

What the installer asks, in order¶

1. Impact manifest — every file, hook and background service this run would touch, shown before the first change. ./install.sh --dry-run stops here.
2. Agent scope — wrapper-scoped (default) or also observe bare claude / copilot / opencode by writing their global configs.
3. Tier — harness · learning · learning-perf · everything, written to ~/.coding/features.yaml. Every later step, the launcher, the container, the status line and the dashboard read that one file.
4. System dependencies — each missing one asks y / N / skip-all.
5. Machine scope — the name of this machine's runtime home ~/.coding/data/<scope>/ (caches only; what is shared lives in each repo, see Per-Repo Tenancy).

Unattended: ./install.sh --yes --features=learning (default tier harness). A re-run asks again with your current tier as the default, so changing tier is just re-running it.

Background services are installed per platform — launchd on macOS, systemd user units on Linux and WSL — and only for the features of the chosen tier. WSL without systemd gets no services and the /etc/wsl.conf fix printed instead.

What the installer is careful about¶

It is deliberately non-intrusive, and each of these is a decision rather than an accident: it prompts before any system-level change, writes a timestamped backup of your shell config before touching it, honours --skip-all to decline every system change, and keeps its data inside the checkout rather than scattering it through your home directory.

What you end up with¶

When it does not work¶

Work in this order, because the failures nest:

1. Is Docker running? (learning tiers and up) Not installed — running. This is the most common first-run failure.
2. Has the shell been reloaded? source ~/.zshrc, or open a new terminal.
3. Did the submodules come down? git submodule update --init --recursive if the clone omitted --recurse-submodules.
4. Then the dashboard at localhost:3032, coding-features status, and Verify & Repair for anything remaining.

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

# Docker Desktop — learning tiers only
brew install --cask docker

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

# Docker — learning tiers only
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER  # Log out and back in

Version Requirements¶

Required — the install aborts without these:

Optional — reported, never fatal:

Installation¶

From the learning tier up, the knowledge services (semantic analysis, constraint monitor, code graph, dashboard) run as containers; the launcher, the agent CLI, the health coordinator, the LLM proxy and obs-api run on the host. The harness tier runs no containers at all.

Step 1: Clone Repository¶

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

git submodule update --init --recursive

Step 2: Run Installer¶

./install.sh

The installer will:

1. Print the impact manifest — everything it may touch
2. Ask the agent scope (default: only coding launches are observed)

3. Ask the tier and write ~/.coding/features.yaml

   

4. Check network reachability (DNS, TCP, TLS) and configure a proxy for the install if it finds one

5. Install the tier's parts — the LLM proxy always; Docker images, knowledge store and viewer from learning up
6. Install the tier's host services (launchd on macOS, systemd user units on Linux / WSL)
7. Add coding, coding-features, semantic and friends to your PATH
8. With a learning tier: set up the coding checkout's own learning repo (.coding/)

Step 2a: See what it will change first¶

./install.sh --dry-run

This prints every path the installer may touch, grouped by scope, then exits without changing anything at all. It is the authoritative list — this page deliberately does not reproduce it, so it cannot go stale.

Step 3: Reload Shell¶

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

Step 4: Verify Installation¶

coding-features status            # the installed tier, feature by feature
curl -s localhost:3034/health     # the health coordinator

Then open the dashboard at localhost:3032: it should read Healthy.

Step 5: Start Coding¶

cd ~/my-project
coding

With a learning tier, the first launch in a repo asks where its learned data goes:

What Gets Installed¶

Configuration Files Created¶

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 (obs-api shown)
lsof -i :12436

# 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¶

• Verify Installation - Detailed verification and repair
• Configuration - API keys and provider setup
• First Usage - Start using coding

Related Documentation¶

• Troubleshooting - Common issues and solutions