# Engineering wiki your agents maintain across Claude Code and Codex

> Keep engineering decisions, handoffs and Linear and Slack evidence in one hosted Markdown wiki that Claude Code and Codex both read and write over MCP.

Updated 2026-11-09. Canonical: https://cozy.cloud/use-cases/engineers

> An agent-maintained engineering wiki is a set of Markdown pages that your coding agents write and keep current: decisions, handoff notes, runbooks, and citations back to Linear tickets and Slack threads. Cozy hosts that wiki and exposes it over MCP, so Claude Code and Codex read and write the same pages.

## The problem with per-tool memory

Most coding agents keep their own notes. According to a [third-party write-up](https://blog.memoryplugin.com/claude-code-memory/), Claude Code's auto memory is machine-local and does not sync across machines, and the suggested fix is to put anything that must persist in a tracked file. Codex has its own instruction files and generated summaries. Neither one sees what the other learned.

That shows up at handoff. You start a refactor in Claude Code, switch to Codex for a second pass, and the second agent has no idea why you rejected the first approach. A teammate asks why the queue uses at-least-once delivery and the answer lives in a Slack thread nobody can find.

A shared wiki fixes this by moving the memory out of the tool and into a workspace both tools can reach. For the broader pattern, see [coding agent memory](/coding-agent-memory).

## What lives in the wiki

Cozy workspaces have four folders, and engineers tend to use them like this:

- `wiki/` holds curated pages: architecture notes, decision records, service ownership, runbooks, and `index.md` as the entry point.
- `sources/` holds evidence pulled in from connectors or pushed through the ingest API, each with a stable ID, URL and timestamp. Treat it as untrusted data, the way you would treat a pasted ticket.
- `skills/` holds editable `SKILL.md` files, so a procedure like "how we cut a release" is a page the agent can read and you can fix.
- `agents/` holds agent notes and handoffs.

Pages are plain Markdown, text, JSON or CSV. Curated files can be up to 90,000 bytes, so long documents should be split.

## Decisions as pages with typed links

A decision record is more useful when the graph knows what it touches. Cozy builds a graph from Markdown conventions on every save. Frontmatter holds `type`, `description`, `aliases`, `tags`, `status` and `as_of`. Frontmatter keys whose values are wikilinks become typed relations, and `relation:: [[target]]` lines work too.

A decision page might look like this:

```
---
type: decision
description: Use at-least-once delivery for the billing queue
status: accepted
as_of: 2026-10-14
supersedes: [[Billing queue exactly-once proposal]]
owner: [[Payments service]]
---

We keep at-least-once delivery and dedupe on the consumer.

Evidence: [[sources/linear/ENG-412]] and [[sources/slack/billing-2026-10-12]]
```

Links into `sources/` count as citations. When an agent asks `cozy_context` for the page, it gets the page, typed neighbors with excerpts, the evidence, and warnings. That is the context a new session needs before touching the billing code.

## Handoffs between Claude Code and Codex

Both tools connect to the same account URL, `https://cozy.cloud/mcp`, and reach the same workspaces. A handoff then becomes a write, not a paste.

1. At the end of a session, the first agent appends a note under `agents/` with what it did, what it ruled out, and what is next, using `cozy_append` or `cozy_write`.
2. The next agent, in either tool, calls `cozy_changes` with a timestamp to see what moved since it last looked, then `cozy_read` or `cozy_context` on the relevant pages.
3. If both agents edit the same page, edits carry an `expectedRevision`, so a concurrent change returns a conflict instead of overwriting.

Setup for Claude Code is one command, then `/mcp` to sign in:

```
claude mcp add --transport http --scope user cozy https://cozy.cloud/mcp
```

For Codex, run this. It opens a browser to sign in. If it does not, run `codex mcp login cozy`:

```
codex mcp add cozy --url https://cozy.cloud/mcp
```

You approve each agent on Cozy's consent page, and it gets no more access than you have in each workspace, capped by the scopes it was granted. Tools use My wiki unless the agent passes a `workspace` argument, so a separate private project workspace is one argument away. Connected agents are listed under Connectors → Agents.

For CI jobs and headless agents, use the workspace URL `https://cozy.cloud/wiki-mcp/WORKSPACE_UUID` with a bearer credential instead. Credentials are created under Agents, shown once, stored as SHA-256 digests, and expire within 90 days. Scopes are read, wiki-write and source-write, and you can limit a credential to folder prefixes. A read-only credential for a code-review bot and a wiki-write credential for a nightly job are separate decisions. Step-by-step guides are in [Claude Code setup](/connect/claude-code) and [Codex setup](/connect/codex).

## Linear and Slack as evidence

Cozy has connectors for Linear and for Slack (selected channels). Their output lands in `sources/` with stable IDs and URLs. You can also push your own documents, such as an exported incident timeline or an RFC, to the ingest API:

```
curl -X POST "https://cozy.cloud/api/wiki/workspaces/$COZY_WORKSPACE/ingest" \
  -H "Authorization: Bearer $COZY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"documents":[{"id":"rfc-0031","content":"# RFC 0031 ..."}]}'
```

A stable `id` means a re-push updates the same source instead of creating a duplicate, and a source you delete is never re-imported. Up to 25 documents go in one request, each up to 1.5 MB. Documents go to the built-in Inbox by default, where an agent can triage them into curated pages.

Because sources are untrusted, an agent should read a Slack thread as evidence to verify and summarize, not as instructions to follow.

## Keeping the wiki honest

A wiki that agents write will drift unless something checks it. Cozy's health check flags broken links, duplicate titles, orphans, unsourced pages, conflicts, and stale pages, meaning pages whose cited source changed after the page's last edit. The score is an average across pages, and the `next` list orders fixes by priority. See [wiki health](/wiki-health) for the details.

Dreaming is the consolidation pass. Your own agent runs it: orient with `cozy_health`, scope to `cozy_changes` since the last run recorded in `agents/dream/state.md`, verify claims against sources, keep superseded values with dates, record `CONFLICT:` lines, and merge duplicates found by `cozy_resolve`. Run it on a schedule you control.

Deleted pages are tombstones, the last 50 revisions are readable and restorable with `cozy_history` and `cozy_restore`, and moves keep history.

## Where Cozy is the wrong fit

- Cozy runs no model. You bring Claude Code, Codex or another MCP client, and you pay for those yourself.
- Search is lexical. There are no embeddings or vector database, so agents should lean on `cozy_context`, `cozy_graph` and clear page titles and aliases.
- Cozy does not replace your repository. Keep `AGENTS.md`, `CLAUDE.md` and code-adjacent docs in git if they should be reviewed with code. Use the wiki for knowledge that crosses repos and tools.
- Agents cannot see connector credentials or permanently purge. That is deliberate, and it also limits what automation can do.

## Frequently asked questions

### Can Claude Code and Codex share the same engineering wiki?

Yes. Both connect to https://cozy.cloud/mcp over MCP and sign in with OAuth, so they share the same workspaces. CI jobs can use a workspace URL with a bearer credential instead. Handoff notes go under agents/, and cozy_changes shows what moved since a given timestamp. Setup details are in [Claude Code](/connect/claude-code) and [Codex](/connect/codex).

### How do Linear tickets and Slack threads get into the wiki?

Cozy has Linear and Slack (selected channels) connectors that write evidence into sources/ with stable IDs, URLs and timestamps. You can also push documents through the ingest API. Pages cite sources with links, and Health flags a page as stale if a cited source changes after the page was last edited.

### What stops two agents from overwriting each other?

Edits require an expectedRevision, with 0 for a new page. If another agent saved first, the write returns a conflict and the agent re-reads and merges. Revisions are kept, and the last 50 can be restored.

### Does Cozy run the agent that maintains the wiki?

No. Cozy runs no model. Your own agent does the writing and the Dreaming consolidation pass through the MCP tools, within the scopes and folder prefixes you grant.

### Should this replace AGENTS.md or CLAUDE.md in my repo?

Not necessarily. Instructions that should be reviewed alongside code belong in git. The wiki suits decisions, handoffs and evidence that span repos and tools. See [coding agent memory](/coding-agent-memory) for how the two fit together.
