# Installation & Setup Guide

CodeWiki provides standalone skills and plugins that can be installed into all major modern coding agents. 

---

## Supported Coding Agents Overview

| Target Agent | Target Flag | Project Skill Directory | Detection Mechanism |
|---|---|---|---|
| **Google Antigravity** | `--target antigravity` | `.agents/skills/` | Automatic project skills discovery |
| **Claude Code** | `--target claude` | `.claude/skills/` or `--plugin-dir` | Skill directory or native Claude plugin |
| **Cursor** | `--target cursor` | `.cursor/skills/` | Project Agent Skills |
| **Codex** | `--target codex` | `.agents/skills/` or `.codex-plugin/` | Skill directory or native Codex manifest |
| **OpenCode** | `--target opencode` | `.opencode/skills/` | Project skills discovery |
| **Upstream Pi** | `--target pi` | `.agents/skills/` or `pi.skills` | Shared skills directory or native package |
| **Oh My Pi (omp)** | `--target omp` | `.omp/skills/` | Project skills directory |
| **Bob** | `--target bob` | `.agents/skills/` | Shared agent skills |
| **Kiro** | `--target kiro` | `.kiro/skills/` | Project skills directory |

---

## Quick Start: Universal Installation

### Method A: Direct with `npx` (No Cloning Required)

From the root of your target project:

```sh
# Install for all supported agents:
npx @nikhil8bph/codewiki --target all

# Or install for a specific agent (e.g. Antigravity, Cursor, Claude):
npx @nikhil8bph/codewiki --target antigravity
```

### Method B: From Git Clone

```sh
# Clone CodeWiki (if not already cloned)
git clone https://github.com/Nikhil8bph/codewiki.git

# Navigate to your target project and run:
node /path/to/codewiki/setup.mjs --target all
```

---

## Agent-Specific Installation Instructions

### 1. Google Antigravity
Antigravity discovers skills in the project's `.agents/skills/` directory.

**Installation:**
```sh
npx @nikhil8bph/codewiki --target antigravity
# Or: node /path/to/codewiki/setup.mjs --target antigravity
```
*Or using `--root`:*
```sh
node setup.mjs --target antigravity --root /path/to/my-project
```

**Installed Location:**
`<my-project>/.agents/skills/{claims-grounding,mermaid-diagrams,okf-format,wiki-init,wiki-query,wiki-update,wiki-visualize,wiki-workspace}/`

**Usage:**
Start or resume your Antigravity agent session. The agent will recognize the skills automatically. Prompt:
> *"Use wiki-init to analyze this codebase and generate repository documentation."*

---

### 2. Anthropic Claude Code
Claude Code supports two installation methods:

#### Method A: Standalone Project Skills (Recommended)
Installs skills directly into Claude Code's project skills directory:
```sh
npx @nikhil8bph/codewiki --target claude
# Or: node /path/to/codewiki/setup.mjs --target claude
```
**Installed Location:** `<my-project>/.claude/skills/`

#### Method B: Native Claude Plugin Directory
Load CodeWiki directly as a plugin using Claude's native `--plugin-dir` flag:
```sh
claude --plugin-dir /path/to/codewiki
```
This loads configuration from `.claude-plugin/plugin.json` without modifying your project files.

**Usage:**
Prompt Claude:
> *"Initialize the CodeWiki for this repository using wiki-init."*

---

### 3. Cursor
Cursor reads project-specific skills from `.cursor/skills/`.

**Installation:**
```sh
npx @nikhil8bph/codewiki --target cursor
# Or: node /path/to/codewiki/setup.mjs --target cursor
```
**Installed Location:** `<my-project>/.cursor/skills/`

**Usage:**
In Cursor's Agent chat (Composer or Chat in Agent mode), ask:
> *"Run wiki-init to build the initial documentation structure."*

---

### 4. Codex (OpenAI / GitHub Codex)
Codex supports both project skills and native plugin configurations.

#### Method A: Project Skills
```sh
npx @nikhil8bph/codewiki --target codex
# Or: node /path/to/codewiki/setup.mjs --target codex
```
**Installed Location:** `<my-project>/.agents/skills/`

#### Method B: Native Codex Plugin
CodeWiki includes `.codex-plugin/plugin.json`. When linking as a Codex plugin bundle, Codex automatically registers all declared skills.

**Usage:**
Ask Codex:
> *"Use wiki-init to create our repository architecture docs."*

---

### 5. OpenCode
OpenCode discovers skills located in `.opencode/skills/`.

**Installation:**
```sh
npx @nikhil8bph/codewiki --target opencode
# Or: node /path/to/codewiki/setup.mjs --target opencode
```
**Installed Location:** `<my-project>/.opencode/skills/`

**Usage:**
Ask OpenCode:
> *"Execute wiki-init to generate source-grounded documentation in codewiki/."*

---

### 6. Upstream Pi
Pi supports two installation methods:

#### Method A: Standalone Project Skills
```sh
npx @nikhil8bph/codewiki --target pi
# Or: node /path/to/codewiki/setup.mjs --target pi
```
**Installed Location:** `<my-project>/.agents/skills/`

#### Method B: Native Pi Local Package
Install CodeWiki as a native Pi package via Pi's CLI:
```sh
pi install --local /path/to/codewiki
```
This uses the `pi.skills` field in `package.json`. In Pi, run `/reload` to activate the package, then call:
```text
/skill:wiki-init
```

---

### 7. Oh My Pi (omp)
For Oh My Pi environments:

**Installation:**
```sh
npx @nikhil8bph/codewiki --target omp
# Or: node /path/to/codewiki/setup.mjs --target omp
```
**Installed Location:** `<my-project>/.omp/skills/`

---

### 8. Bob
For Bob agent environments:

**Installation:**
```sh
npx @nikhil8bph/codewiki --target bob
# Or: node /path/to/codewiki/setup.mjs --target bob
```
**Installed Location:** `<my-project>/.agents/skills/`

---

### 9. Kiro
For Kiro agent environments:

**Installation:**
```sh
npx @nikhil8bph/codewiki --target kiro
# Or: node /path/to/codewiki/setup.mjs --target kiro
```
**Installed Location:** `<my-project>/.kiro/skills/`

---

## Advanced Options

### Conflict Detection & `--force`
The installer inspects existing files before writing. If a target file exists and its content differs from the plugin version, the installer halts to prevent overwriting custom changes:

```text
Error: Existing skill file differs from plugin source: .agents/skills/wiki-init/SKILL.md
Review differences or rerun with --force to overwrite.
```

To explicitly overwrite existing files with the bundled versions:
```sh
node /path/to/codewiki/setup.mjs --target all --force
```

### Non-Destructive Guarantee
`setup.mjs` strictly writes skill files only:
- It **never** touches or alters configuration files (`.mcp.json`, `opencode.jsonc`, `.cursor/`, etc.).
- It **never** writes outside the project root directory.
- It rejects destinations that attempt to resolve outside the project root or through directory symlinks.