# Overview
> What loopany exposes (CLI, workspace, skills), runtime assumptions (Bun, $LOOPANY_HOME), and the shortest path from init to a running mission-backed brain.
- 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
- `README.md`
- `CLAUDE.md`
- `src/cli.ts`
- `src/version.ts`
- `package.json`
- `skills/loopany-resolver/SKILL.md`
---
---
title: "Overview"
description: "What loopany exposes (CLI, workspace, skills), runtime assumptions (Bun, $LOOPANY_HOME), and the shortest path from init to a running mission-backed brain."
---
loopany ships as a Bun-driven TypeScript CLI (`src/cli.ts`, entry `loopany` in `package.json`) that reads and writes a single per-user workspace under `$LOOPANY_HOME` (default `~/loopany`). Judgment lives in markdown skills under `skills/`; deterministic validation, storage, graph indexing, and search run in code. The binary reports `0.2.0` for both `loopany --version` and workspace `schemaVersion` (`src/version.ts`); `bootstrap()` refuses most commands when those versions diverge.
## What loopany exposes
Three cooperating surfaces attach any agent harness (Claude Code, Codex, Hermes, custom) to one persistent brain:
| Surface | Location | Role |
|---------|----------|------|
| **CLI** | `loopany` → `src/cli.ts` | Artifact CRUD, reference graph, domains, followups, hybrid search, migrations, `doctor`, optional `factory` UI |
| **Workspace** | `$LOOPANY_HOME` | Canonical markdown artifacts, `config.yaml`, append-only `references.jsonl` and `audit.jsonl`, optional derived `search.db` |
| **Skills** | `skills/loopany-*/SKILL.md` in the cloned repo | Routing, capture, reflect, review, kind playbooks — read by the agent, not executed by the runtime |
```mermaid
flowchart TB
subgraph harness["Agent harness"]
Agent["Agent session"]
end
subgraph skills["Skills (markdown, repo)"]
Resolver["loopany-resolver/SKILL.md"]
Core["loopany-core + kinds/*.md"]
Capture["loopany-capture"]
Reflect["loopany-reflect"]
Review["loopany-review"]
end
subgraph cli["CLI runtime (Bun / TypeScript)"]
CLI["src/cli.ts"]
Engine["bootstrap() → engine.ts"]
Store["ArtifactStore"]
Refs["ReferenceGraph"]
Index["ArtifactIndex / search.db"]
end
subgraph disk["$LOOPANY_HOME"]
Artifacts["artifacts/<dirName>/<slug>.md"]
Config["config.yaml"]
RefsFile["references.jsonl"]
Audit["audit.jsonl"]
end
Agent -->|"Read SKILL.md on demand"| Resolver
Resolver --> Core
Resolver --> Capture
Resolver --> Reflect
Resolver --> Review
Agent -->|"loopany …"| CLI
CLI --> Engine
Engine --> Store
Engine --> Refs
Engine --> Index
Store --> Artifacts
Refs --> RefsFile
Engine --> Config
CLI --> Audit
```
Skills are portable markdown packs — not tied to a model provider. Host memory injection (for example `injections/resolver-memory.md` into `~/.claude/CLAUDE.md` or `AGENTS.md`) only points at `~/loopany-src/skills/loopany-resolver/SKILL.md`; skill content can change via `git pull` without re-running injection.
## Runtime assumptions
Required to run and link the CLI (`bun install`, `bun link`, `bun run src/cli.ts`). A compiled binary is optional via `bun build --compile --outfile bin/loopany src/cli.ts`.
Workspace root. Defaults to `~/loopany` when unset (`getWorkspaceRoot()` in `src/core/engine.ts`).
When set to `1`, skips `schemaVersion` vs `SCHEMA_VERSION` guard — used by migration scripts and honored by `bootstrap({ skipVersionCheck: true })`.
`CLAUDE.md` lists Node 22+ as an alternative runtime; the shipped scripts and tests target Bun.
Workspace detection is minimal: `bootstrap()` requires `$LOOPANY_HOME/kinds` to exist (created by `loopany init`). Missing workspace → `WorkspaceNotFoundError`. Stale `config.yaml#schemaVersion` → `SchemaVersionMismatchError` with a pointer to `loopany migrate` and `skills/migrations/v*-to-v*/SKILL.md`.
## Workspace layout (v0.2)
After `loopany init`, expect:
:::files
$LOOPANY_HOME/
├── config.yaml # schemaVersion, enabled_domains
├── kinds/ # copied from skills/loopany-core/kinds/*.md
├── artifacts/
│ ├── missions/ # mission (flat)
│ ├── people/ # person (flat)
│ ├── tasks/ # task (default dirName: tasks)
│ ├── notes/
│ ├── journal/YYYY/ # journal (slugLayout: year)
│ └── … # other kinds → artifacts//
├── references.jsonl # append-only graph edges
├── audit.jsonl # CLI operation log (best-effort)
└── search.db # optional; rebuilt by loopany reindex
:::
Artifact IDs are **slugs** (no kind prefix). Pass `--slug` on create for anything you will cite with `[[slug]]`; otherwise the CLI derives from `--title` or mints `YYYYMMDD-HHMMSS-xxx` (`src/cli.ts` help text).
Bundled core kinds (copied at init): `mission`, `task`, `signal`, `person`, `note`, `learning`, `skill-proposal`, `brief`, `journal`. Kind schemas and status machines live in markdown under `kinds/`; the runtime builds Zod validators dynamically (`KindRegistry`).
## CLI command surface (summary)
Most mutating commands call `bootstrap()`, write JSON to stdout, and append an audit row when the workspace exists.
| Group | Commands |
|-------|----------|
| Init | `init` |
| Artifacts | `artifact create \| get \| list \| append \| status \| set` |
| Graph | `refs`, `refs add`, `trace` |
| Domains | `domain list \| enable \| disable` |
| Scheduling | `followups [--due today\|overdue]` |
| Search | `search`, `reindex [--force] [--no-embed]` |
| UI | `factory [--port N] [--no-open]` |
| System | `kind list`, `doctor`, `migrate`, `--version` |
`doctor` and `migrate` call `bootstrap({ skipVersionCheck: true })` so they can report or fix version skew instead of crashing first.
## Skills library and resolver gate
Every loopany interaction is expected to start at `skills/loopany-resolver/SKILL.md`:
```bash
loopany artifact list --kind mission --status active
```
**No active mission → run `ONBOARDING.md` and stop.** Core and capture skills repeat the same bootstrap rule.
| Skill | Triggers (examples) |
|-------|---------------------|
| `loopany-resolver` | Session start, ambiguous intent, multi-skill workflows |
| `loopany-core` | Any artifact CRUD; relation verb choice |
| `loopany-capture` | Substantive work ended (PR shipped, incident resolved) |
| `loopany-reflect` | ≥3 done tasks with outcomes; accept/reject skill-proposals |
| `loopany-review` | Daily followups, weekly doctor/sweep, monthly mission drift |
Cross-skill chains documented in the resolver include **capture → core**, **capture → reflect** (after ≥3 captures), **reflect → core** (writes `learning` / `skill-proposal`), and **review → reflect** on weekly resolution thresholds.
Agents **never edit skill files directly** — behavior changes flow through `skill-proposal` artifacts, user accept/reject, then git-backed diffs (see self-improvement docs).
## Mission-backed brain
A mission artifact (`kinds/mission.md`) is the standing intention the brain serves: long-running pursuit, `status: active`, body sections like `## Current hypothesis`. Tasks, signals, and briefs relate to it via `mentions`, `domain`, or graph edges — not by replacing the mission kind.
`loopany doctor` treats onboarding as incomplete without:
- a `self` **person** artifact, and
- at least one **mission** with `status: active`
Until both exist, the resolver intentionally blocks routine work — the workspace has no declared purpose.
## Shortest path: init → running brain
```bash
git clone https://github.com/superdesigndev/loopany.git ~/loopany-src && cd ~/loopany-src
curl -fsSL https://bun.sh/install | bash
export PATH="$HOME/.bun/bin:$PATH"
bun install && bun link
loopany --version
```
```bash
loopany init
# Optional: LOOPANY_HOME=/path/to/brain loopany init
```
Creates `$LOOPANY_HOME/kinds`, `artifacts/`, and `config.yaml` with `schemaVersion: 0.2.0`. Idempotent — existing files are preserved. If no `artifacts/missions/*.md` exists, init prints a pointer to `ONBOARDING.md`.
Read `ONBOARDING.md` once. The agent runs a short conversation, then creates artifacts — including one `mission` with `status: active` and usually a `person` slug `self`. Do not re-run if an active mission already exists.
Example mission create (fields per `kinds/mission.md`):
```bash
loopany artifact create --kind mission \
--slug ship-v1 \
--title "Ship loopany v1" \
--status active \
--content-file -
```
Append `injections/resolver-memory.md` so every session ends by re-reading the resolver (Claude Code: `~/.claude/CLAUDE.md`; Codex: `~/AGENTS.md`). Details in `INSTALL_FOR_AGENTS.md` Step 5.
```bash
loopany doctor
loopany artifact list --kind mission --status active
```
Exit `0` from `doctor` means workspace, kinds, artifacts, references, and onboarding checks passed. Warnings (for example tasks without `mentions` of a mission) do not fail the run.
After verification, normal operation is: resolver → appropriate skill → `loopany artifact …` / `loopany refs …`. End-of-task capture and periodic review keep the graph and outcomes current; `loopany reindex` rebuilds search when needed.
## Design constraints (operational)
- **Thin harness, fat skills** — code handles I/O, validation, and graph indexing; judgment stays in SKILL.md files.
- **Markdown + JSONL source of truth** — no database; `search.db` is disposable.
- **Immutable cited artifacts** — append body sections, transition `status`, or supersede; do not edit agent-produced history in place.
- **Open registries** — `kind` and `relation` extend via config/markdown, not TypeScript enums.
- **Agent proposes, human accepts** — new kinds, domains, and skill changes go through explicit artifacts and user decisions.
Unit and E2E tests run with `bun test`; skill regression (`test/skill-regression.sh`) exercises the five skills against a fresh `LOOPANY_HOME` per scenario.
## Related pages
Clone, Bun, `bun link`, PATH, `$LOOPANY_HOME`, and resolver injection into agent hosts.
First session: mission, task, reference edge, and `doctor`.
On-disk layout, slug-as-id rules, and v0.2 storage paths.
Resolver routing, skill packs, and harness-neutral memory injection.
`loopany init`, bundled kinds, onboarding, cadence, and doctor checks.
Full command list, flags, and JSON stdout conventions.