# Installation

> Clone the repo, install Bun, link the CLI, set PATH, initialize $LOOPANY_HOME, and wire the resolver injection into Claude Code, Codex, or other agent hosts.

- Repository: superdesigndev/loopany
- GitHub: https://github.com/superdesigndev/loopany
- Human docs: https://grok-wiki.com/public/docs/superdesigndev-loopany-97bd9ab97ae8
- Complete Markdown: https://grok-wiki.com/public/docs/superdesigndev-loopany-97bd9ab97ae8/llms-full.txt

## Source Files

- `INSTALL_FOR_AGENTS.md`
- `package.json`
- `src/cli.ts`
- `injections/resolver-memory.md`
- `src/commands/init.ts`
- `ONBOARDING.md`

---

---
title: "Installation"
description: "Clone the repo, install Bun, link the CLI, set PATH, initialize $LOOPANY_HOME, and wire the resolver injection into Claude Code, Codex, or other agent hosts."
---

loopany ships as a Bun-linked CLI (`package.json` → `src/cli.ts`) that scaffolds a per-user workspace at `$LOOPANY_HOME` (default `~/loopany`) via `loopany init`, while the skill library and resolver injection stay in the cloned repository checkout (conventionally `~/loopany-src`).

## Prerequisites

| Requirement | Notes |
|-------------|--------|
| [Bun](https://bun.sh) | Runtime and package manager; the CLI shebang is `#!/usr/bin/env bun`. |
| Git | Clone `https://github.com/superdesigndev/loopany`. |
| Agent host (optional) | Claude Code, Codex, Hermes, OpenClaw, or any harness that can read markdown skills and append persistent memory. |

<Note>
`package.json` lists version `0.1.0`; `loopany --version` prints the binary version from `src/version.ts` (currently `0.2.0` with workspace schema `0.2.0`).
</Note>

## Repository layout after clone

Two on-disk locations matter: the **source checkout** (CLI + skills + injections) and the **workspace** (artifacts + copied kinds + config).

```text
~/loopany-src/                    # git clone (path is your choice)
├── src/cli.ts                    # bin entry: loopany
├── skills/
│   ├── loopany-resolver/SKILL.md # dispatcher — read at end of tasks
│   ├── loopany-core/kinds/*.md   # bundled kind defs copied by init
│   └── loopany-capture|reflect|review/ ...
└── injections/resolver-memory.md # host memory snippet

~/loopany/                        # $LOOPANY_HOME (default)
├── config.yaml                   # schemaVersion, enabled_domains
├── kinds/*.md                    # copied once from bundled kinds
├── artifacts/                    # markdown artifacts (created on use)
├── references.jsonl              # created on first graph edge write
└── audit.jsonl                   # created on first post-init CLI op
```

## Install the CLI

<Steps>
<Step title="Clone the repository">

```bash
git clone https://github.com/superdesigndev/loopany.git ~/loopany-src
cd ~/loopany-src
```

</Step>

<Step title="Install Bun (if needed)">

```bash
curl -fsSL https://bun.sh/install | bash
export PATH="$HOME/.bun/bin:$PATH"
```

Persist `export PATH="$HOME/.bun/bin:$PATH"` in `~/.zshrc` or `~/.bashrc`, then `source` the file.

</Step>

<Step title="Install dependencies and link globally">

```bash
bun install && bun link
```

`bun link` registers the `loopany` bin from `package.json` (`"loopany": "./src/cli.ts"`) on your PATH via Bun’s global link.

</Step>

<Step title="Verify the CLI">

```bash
loopany --version
```

<Check>
Expected output shape: `loopany 0.2.0` (semver from `src/version.ts`).
</Check>

If `loopany` is not found, Bun’s bin directory is not on `PATH` — add `$HOME/.bun/bin` and open a new shell.

</Step>
</Steps>

### Optional: compiled binary

For a standalone executable without invoking `bun run` each time:

```bash
bun run build
# writes bin/loopany via: bun build --compile --outfile bin/loopany src/cli.ts
```

Add the `bin/` directory to `PATH`, or copy `bin/loopany` somewhere already on `PATH`.

## Initialize the workspace

`loopany init` scaffolds `$LOOPANY_HOME`, copies bundled kind definitions from `skills/loopany-core/kinds/`, and writes `config.yaml` with the current `SCHEMA_VERSION`. The command is **idempotent**: existing files are left untouched; only missing paths and kind files are created.

```bash
loopany init
```

<ResponseExample>

```text
Initialized loopany workspace at /Users/you/loopany
Created N file(s).

NEXT — read ONBOARDING.md and start the onboarding conversation.
Without an active mission artifact, the brain has no reason to exist.
```

</ResponseExample>

The `NEXT` block appears when `artifacts/missions/` has no `.md` files yet (`needsOnboarding` in `runInit`).

### Custom workspace location

<ParamField body="LOOPANY_HOME" type="path">
Overrides the default `~/loopany`. Resolved in `getWorkspaceRoot()` as `process.env.LOOPANY_HOME ?? join(homedir(), 'loopany')`. Applies to every command after export — not only `init`.
</ParamField>

```bash
export LOOPANY_HOME=/path/to/brain
loopany init
```

<Warning>
Most commands call `bootstrap()`, which requires a `kinds/` directory under `$LOOPANY_HOME`. Without `loopany init`, you get `WorkspaceNotFoundError: No loopany workspace at … Run loopany init first.`
</Warning>

### What `init` creates

| Path | Created by init |
|------|-----------------|
| `$LOOPANY_HOME/` | Yes (if missing) |
| `kinds/` | Yes; copies `task`, `signal`, `person`, `mission`, `note`, `learning`, `skill-proposal`, `brief`, `journal` from bundled kinds |
| `artifacts/` | Empty directory |
| `config.yaml` | Yes, with `schemaVersion: <SCHEMA_VERSION>` |
| `references.jsonl` | No — first `refs add` or append creates the file |
| `domains/` | No — created when domains are enabled later |

## Agent-driven install (harness paste)

Hosts can fetch the canonical agent install doc without shell steps from the user:

```text
Retrieve and follow the instructions at:
https://raw.githubusercontent.com/superdesigndev/loopany/main/INSTALL_FOR_AGENTS.md
```

That document covers clone → link → `init` → onboarding → cadence choice → resolver injection → `loopany doctor`, including tone rules (keep CLI vocabulary out of user-facing chat).

## Wire resolver injection into agent hosts

loopany does not load skills at runtime. Agents **read** markdown under `~/loopany-src/skills/` on demand. The injection only adds one persistent rule: before the final reply on user-requested work, read `~/loopany-src/skills/loopany-resolver/SKILL.md`.

Canonical snippet (`injections/resolver-memory.md`):

```markdown
## loopany skill resolver

Dispatcher lives at `~/loopany-src/skills/loopany-resolver/SKILL.md`.

**At the end of every user-requested task**, before the final message
where you'd normally report "done" / "shipped" / "here is the answer",
**Read `~/loopany-src/skills/loopany-resolver/SKILL.md` first**, then reply.
```

Adjust `~/loopany-src` if you cloned elsewhere; the injection path must match your checkout.

### Coding CLIs (Claude Code, Codex)

<Tabs>
<Tab title="Claude Code (user-wide)">

Appends once (idempotent `grep` guard):

```bash
grep -q "loopany skill resolver" ~/.claude/CLAUDE.md 2>/dev/null || \
  cat ~/loopany-src/injections/resolver-memory.md >> ~/.claude/CLAUDE.md
```

</Tab>
<Tab title="Codex">

```bash
TARGET="$HOME/AGENTS.md"
grep -q "loopany skill resolver" "$TARGET" 2>/dev/null || \
  cat ~/loopany-src/injections/resolver-memory.md >> "$TARGET"
```

</Tab>
<Tab title="Claude Code (per-project)">

Append to `./CLAUDE.md` in the project root, or to `~/.claude/projects/<slug>/memory/MEMORY.md` where `<slug>` is the project absolute path with `/` replaced by `-` (e.g. `/Users/x/dev/y` → `-Users-x-dev-y`).

</Tab>
</Tabs>

### Agent platforms (Hermes, OpenClaw, …)

Register the same text via the host memory primitive:

```bash
/memory add "$(cat ~/loopany-src/injections/resolver-memory.md)"
```

If multi-line values are rejected, collapse newlines: `tr '\n' ' ' < ~/loopany-src/injections/resolver-memory.md`.

### Verify injection

File checks (concrete, not self-query):

```bash
grep -l "loopany skill resolver" ~/.claude/CLAUDE.md ~/AGENTS.md 2>/dev/null
test -f ~/loopany-src/skills/loopany-resolver/SKILL.md && echo "RESOLVER present"
```

Start a **fresh** session and ask the agent where the loopany resolver lives. A correct answer cites `~/loopany-src/skills/loopany-resolver/SKILL.md` without searching — otherwise the memory file exists but did not load (check host memory scope rules).

<Info>
Re-running the `grep -q … || cat …` install is a no-op when the marker string is already present. `git pull` in `~/loopany-src` updates skill content; you do not need to re-inject unless the pointer path changed. A `doctor` check for resolver registration is noted as roadmap, not implemented yet.
</Info>

## Runtime integration model

```mermaid
flowchart LR
  subgraph repo ["~/loopany-src (checkout)"]
    CLI["src/cli.ts / loopany bin"]
    SK["skills/loopany-*"]
    INJ["injections/resolver-memory.md"]
  end
  subgraph ws ["$LOOPANY_HOME"]
    CFG["config.yaml"]
    KD["kinds/*.md"]
    ART["artifacts/**"]
    REF["references.jsonl"]
  end
  subgraph host ["Agent host memory"]
    MEM["CLAUDE.md / AGENTS.md / /memory"]
  end
  CLI -->|"loopany init"| ws
  INJ -->|"append once"| MEM
  MEM -.->|"Read resolver before final reply"| SK
  SK -->|"loopany artifact *"| CLI
  CLI --> ws
```

## Post-install: onboarding and cadence

After `init` with no mission artifacts:

1. Read `ONBOARDING.md` and run the conversation (creates `self` person + active `mission` artifacts).
2. Choose cadence **without asking the user** on coding CLIs: default is session-boundary prompts (`loopany followups --due today`, weekly sweep/reflect proposals) rather than host cron — Claude Code recurring cron expires after ~7 days per `INSTALL_FOR_AGENTS.md`.

`loopany doctor` treats incomplete onboarding as **fail** until `self` exists and at least one `mission` has `status: active`.

## Verify installation

```bash
loopany doctor
```

| Exit code | Meaning |
|-----------|---------|
| `0` | All non-fail checks passed |
| `1` | At least one check failed (schema version, kinds parse, artifacts, references, onboarding, …) |

Machine-readable report:

```bash
loopany doctor --format json
```

Typical checks after a full agent install: `workspace`, `schema version`, `kinds`, `artifacts`, `references`, `onboarding` (and warnings for `mission coverage`, `domain coverage`).

### Schema version mismatch

If `config.yaml#schemaVersion` lags the binary’s `SCHEMA_VERSION`, normal commands raise `SchemaVersionMismatchError` and point at `loopany migrate`. `doctor` and `migrate` bypass the guard to report or fix the workspace.

<ParamField body="LOOPANY_SKIP_VERSION_CHECK" type="string">
Set to `1` to skip schema guard (migration scripts and tests).
</ParamField>

## Environment variables

| Variable | Default | Role |
|----------|---------|------|
| `LOOPANY_HOME` | `~/loopany` | Workspace root for all CLI operations |
| `LOOPANY_SKIP_VERSION_CHECK` | unset | When `1`, skips `schemaVersion` vs binary check |
| `LOOPANY_EDITOR` | OS default | Optional editor override for `factory` UI (see `src/ui/editor.ts`) |

## Troubleshooting

| Symptom | Likely cause | Fix |
|---------|----------------|-----|
| `loopany: command not found` | Bun bin not on `PATH` | Add `$HOME/.bun/bin` to shell rc |
| `No loopany workspace at …` | Missing `init` or wrong `LOOPANY_HOME` | `export LOOPANY_HOME=…` then `loopany init` |
| `SchemaVersionMismatchError` | Stale workspace | `loopany migrate` per error message |
| Resolver not followed | Injection missing or wrong scope | Re-run idempotent append; fresh session; verify `grep` |
| `doctor` onboarding fail | No `self` / no active mission | Complete `ONBOARDING.md` Phase 3 |
| Kind file missing after init | Init skipped copy because file existed | Compare `$LOOPANY_HOME/kinds/` with `skills/loopany-core/kinds/` manually |

## Related pages

<CardGroup>
<Card title="Overview" href="/overview">
What loopany exposes (CLI, workspace, skills) and the shortest path from init to a mission-backed brain.
</Card>
<Card title="Quickstart" href="/quickstart">
First session: mission, task, reference edge, and doctor.
</Card>
<Card title="Workspace setup" href="/workspace-setup">
Post-init verification, onboarding completion, and cadence registration.
</Card>
<Card title="Configuration reference" href="/configuration-reference">
`config.yaml` keys and environment variables in depth.
</Card>
<Card title="Doctor and troubleshooting" href="/doctor-and-troubleshooting">
Full doctor check list and recovery steps.
</Card>
<Card title="Skills library" href="/skills-library">
Resolver routing table and skill pack layout.
</Card>
</CardGroup>