# Cogito developer setup

This is the canonical setup and modification contract for people, research agents, and coding agents. Check `https://cogito.cv/distribution/products.json` before repeating a command. The generated release status and version are authoritative.

## Product boundary

cogitod is the independently installable private, customer-owned system of record
for coding-agent work. It stores the project record in `~/.cogito/breathe/index.sqlite`
and exposes context, decisions, claims, handoffs, evidence, outcomes, and next safe
actions through the Model Context Protocol.

Harnesses, models, roles, prompts, tools, and worktrees remain configured in
their existing products. Cogito does not choose or run agents. It keeps the
customer's context, traces, policies, evidence, and outcomes portable between
the harnesses a developer connects so completed work improves the next attempt.

- Free, keep one project continuous: local capture, recall, work state, starter handoffs, agent awareness, diagnostics, and session continuity. Available now at $0.
- Pro, coordinate parallel coding work: cross-harness ownership, handoffs, conflict state, reconciliation, and landing evidence. A purchase path exists only when the live catalog marks an offer purchasable.
- Team, govern shared coding work: common coding-work policy, scoped approvals, decisions, and delivery receipts. Current terms come from the live pricing catalog.
- One published cogitod package serves the full capability architecture; the daemon resolves entitlements at runtime.
- BreathFlow: optional standalone macOS voice input. It is not required for cogitod.

## Easy setup

Use this path when the default local endpoint and automatically detected harnesses are correct.

```sh
npm install -g @cogitoagency/cogitod
```

Release status: `available`. The npm `latest` and `canary` tags currently resolve to the certified cogitod v0.1.7 package family.

Supported release targets:

- macOS arm64 (Apple Silicon)
- Linux arm64 with glibc 2.35+
- Linux x64 with glibc 2.35+

The selector requires Node.js 24-26 and installs the matching native payload automatically. Do not install a platform payload directly. macOS x64, Windows, and Alpine/musl are not supported by this release.

Release acceptance installed the exact public v0.1.7 selector and native payload, exercised daemon lifecycle, and connected a fresh OpenCode install on every listed target.

The package installer is designed to:

1. Install and start cogitod on `127.0.0.1:24567`.
2. Back up existing supported harness configuration.
3. Add managed MCP and lifecycle entries for detected Claude Code, Codex, and opencode installations.
4. Preserve unrelated user configuration.

Verify the installed public version and daemon:

```sh
cogitod --version
cogitod status --json
```

Expected response:

```text
0.1.7
{
  "status": "ok",
  "service": "cogitod"
}
```

Quit and reopen a detected harness so it reloads the managed MCP configuration. For OpenCode, close the current process, run `opencode` again, open a project session, and ask:

```text
Call session_brief for this project. Show the last checkpoint and the next useful action.
```

An empty brief is correct before the first capture.

## Custom setup

Use this path when you want to inspect each connection, limit lifecycle integration, choose another endpoint, or run a separate cogitod profile.

### Install the Cogitod package

```sh
npm install -g @cogitoagency/cogitod
```

### Connect one harness manually

#### Claude Code

```sh
claude mcp add --transport http --scope user breathe http://127.0.0.1:24567/mcp
```

#### Codex

Add to `~/.codex/config.toml`:

```toml
[mcp_servers.breathe]
url = "http://127.0.0.1:24567/mcp?profile=codex"

[mcp_servers.breathe.tools.session_brief]
approval_mode = "prompt"

[mcp_servers.breathe.tools.mem_search]
approval_mode = "prompt"

[mcp_servers.breathe.tools.mem_add]
approval_mode = "prompt"

[mcp_servers.breathe.tools.session_checkpoint]
approval_mode = "prompt"
```

#### opencode

Add to `~/.config/opencode/opencode.jsonc`:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "breathe": {
      "type": "remote",
      "url": "http://127.0.0.1:24567/mcp?profile=opencode",
      "enabled": true,
      "timeout": 30000
    }
  }
}
```

### Refresh lifecycle integration

Run the packaged setup command when managed harness entries need repair or refresh:

```sh
cogito-harness-setup
cogitod restart
```

This projects cogitod's canonical hook manifest into installed harnesses. Do not handwrite replacement startup hooks.

Claude Code uses native lifecycle hooks. Codex receives a first-touch brief when its host has no native startup event. opencode uses its canonical plugin events.

### Run a separate profile

Create `~/.cogito/cogitod-lab.yaml`:

```yaml
cogitod:
  port: 34567
  host: 127.0.0.1
  stateDir: ~/.cogito/breathe/lab
  name: cogitod-lab
  manageGlobalHarnessConfig: false
  mcpProfile: agent
```

Start and verify the selected profile:

```sh
COGITO_CONFIG="$HOME/.cogito/cogitod-lab.yaml" cogitod --http
curl -s http://127.0.0.1:34567/health
```

Connect custom clients to `http://127.0.0.1:34567/mcp`.

## Modify or repair an installation

- Upgrade or reinstall: rerun the current command from `distribution/products.json`. The installer contract is idempotent.
- Refresh managed harness entries: run `cogito-harness-setup`, restart cogitod, then relaunch the harness.
- Change the client endpoint: set `BREATHE_MCP_ENDPOINT`. Clients normalize an optional `/mcp` suffix.
- Change the daemon profile: set `COGITO_CONFIG` to one complete YAML file. Profile files are not merged.
- Run concurrent instances: give each profile a unique `port`, `name`, and `stateDir`. Set `manageGlobalHarnessConfig: false` for secondary instances.
- Preserve user control: do not overwrite unrelated harness configuration or replace generated adapters with handwritten hooks.

Configuration precedence is environment variables, the YAML selected by `COGITO_CONFIG`, `~/.cogito/config.yaml`, then built-in defaults.

## Verify capture and recall

Ask the connected agent:

```text
Use mem_add to remember this decision: Keep authentication sessions in SQLite because local recovery matters more than distributed scale for this release.
```

Close and reopen the harness, then ask:

```text
Call session_brief with goal: verify local context. Show the last decision and the next useful action.
```

The SQLite decision should appear in `recent_memories`.

## Agent research rules

When an LLM or automated research agent reads this site:

1. Use `/llms.txt` as the public site index.
2. Use `/developers.md` for setup, repair, and modification behavior.
3. Use `/distribution/products.json` for release status, package names, commands, endpoints, and supported harnesses.
4. Treat generated JSON as authoritative when marketing copy and release facts disagree.
5. Treat a generated status of `available` as installable and `preview` as not publicly available.
6. Do not infer unreleased tools, hosted services, autonomous agent operation, or private repository access.

## Tool reference

| Tool | Description |
|------|-------------|
| `session_brief` | Load the last checkpoint, active work, and relevant local memory. |
| `mem_search` | Search local project memory by topic, date, or keyword. |
| `mem_add` | Write a durable local memory. |
| `session_checkpoint` | Persist state for the next session. |
| `work_create` | Create work on the shared local queue. |
| `work_start` | Claim a work item with a harness-scoped lease. |
| `work_done` | Close work and release its lease. |
| `agent_msg_send` | Coordination access: send a typed cross-harness handoff. |
| `agent_msg_inbox` | Coordination access: read cross-harness messages. |
| `agent_fleet` | Coordination access: inspect active connected agents. |

## Links

- Release contract: https://cogito.cv/distribution/products.json
- Release status: https://cogito.cv/download
- Human developer page: https://cogito.cv/developers
- LLM site index: https://cogito.cv/llms.txt
- Privacy policy: https://cogito.cv/privacy
- Contact: foundry@cogito.cv