Metadata-Version: 2.3
Name: collossal
Version: 0.1.0
Summary: Collossal CLI: connects your coding agent to your team's sessions, memory and rooms.
Author: Vipul
Author-email: Vipul <vilulgupta2802@gmail.com>
Requires-Dist: mcp[cli]>=2.2.0
Requires-Dist: httpx2>=2.12.0
Requires-Dist: websockets>=13.0
Requires-Python: >=3.14
Description-Content-Type: text/markdown

# Collossal MCP

Shared memory for coding agents. Runs on a developer's machine and talks to the
Collossal API over HTTPS — it holds an API key and never database credentials.

## Setup

One command per machine — the dashboard's Setup page shows it with your
addresses filled in:

```bash
curl -fsSL https://<your-collossal>/install.sh | sh -s -- --api-url https://<your-collossal>/api/v1
```

That installs the `collossal` command (with uv, which brings its own Python) and
runs `collossal install`, which:

1. **Signs the machine in through the browser.** It shows a code and opens the
   dashboard; you check the code and approve. The machine receives an API key
   of your own — nothing to copy — saved to `~/.collossal/config.json` (0600).
2. **Sets up Claude Code for every project:** the hooks below go into
   `~/.claude/settings.json` (your other settings are kept, and the original is
   backed up once), and the MCP server is registered with
   `claude mcp add --scope user`.
3. **Uploads your past sessions** from `~/.claude/projects` — every one,
   whatever it ran in — with their real timestamps, titles and redaction, so
   your history appears on the dashboard, not just what happens from now on.

From then on every Claude Code session on the machine streams to your team's
Sessions tab as it happens, and every teammate can open it. Nothing has to be
connected first: a session is labelled by the repository it ran in (or, begun
in a folder holding several, the one it works in most), or by its folder. A
repository connected to a project additionally gets memory — decisions
anchored to its files.

Each person chooses which of their sessions the team sees, under **Sessions →
Configure**: all of them (the default), or only those in the repositories and
folders they pick. The choice applies at once to past sessions as well as new
ones. A session outside it is still recorded, and its owner still sees it under
My sessions — nobody else does: not teammates, not workspace admins, not an
agent's `team_sessions` or a handoff. Setting it before running the installer
keeps the upload of past sessions within it from the start.

Until the CLI is published, install it from this checkout instead:

```bash
uv tool install --editable /path/to/main-mcp && collossal install --api-url http://localhost:3000/api/v1
```

| Command | Does |
|---|---|
| `collossal install` | All of the above; safe to run again |
| `collossal import` | Upload past sessions again — e.g. after connecting another repo |
| `collossal status` | Who this machine is signed in as, and what is set up |
| `collossal doctor` | The same, plus what is wrong and how to fix it |
| `collossal login` | Sign in again without changing anything else |
| `collossal uninstall` | Remove the hooks, the MCP server and the sign-in |

`COLLOSSAL_API_KEY` and `COLLOSSAL_API_URL` still work and take precedence over
the saved sign-in — for CI, or to pin one project to a different workspace.

## Tools

**`memory_write`** — records a decision and anchors it to the files it governs.

**`memory_search`** — natural-language search across the project. Results can
come from a *different repository* than the one being edited; that is the point.

**`memory_for_files`** — decisions attached to specific files. Needs no query,
so it surfaces context an agent would not have known to search for. Anchors
belong to a repo, so this looks within the current one; `memory_search` is the
cross-repo path.

**`team_sessions`** — teammates' recent agent sessions, to inherit from. Lists
the whole workspace's, whatever repository or folder they ran in; excludes your
own and any a teammate keeps private, and omits sessions that recorded nothing
— an empty run is noise in a list an agent acts on.

**`session_handoff`** — takes a teammate's session over: where the work is, the
end of their conversation, and the decisions already anchored to the files
involved, written for the receiving agent to read on its first turn. Accepts a
session id or a pasted dashboard link. No agent will adopt a foreign session id,
so what transfers is the context, not the process.

The agent supplies the claim, rationale, and files. Everything identifying —
repo, branch, commit, project — is read from the git checkout, because asking an
agent for a project id invites it to guess.

File paths are normalised to repo-relative before storage: an absolute path
would anchor the memory to one machine's directory layout and never match for a
teammate.

A decision replaced by a newer one is still returned, labelled `[SUPERSEDED]`
with the claim that replaced it, stated *before* its rationale — an agent must
not be able to read stale reasoning without first seeing that it no longer
holds.

## Automatic capture

Two hooks, because the transcript on disk already holds every tool call and
message — there is nothing to gain from hooking each tool.

| Hook | Does |
|---|---|
| `SessionStart` | Injects this project's decisions into the new session, and starts streaming it to the dashboard |
| `Stop` | Captures what the turn taught, and delivers any instruction a teammate sent |
| `SessionEnd` | Ships the rest of the transcript, and uploads the whole session if it was never streamed — one that began before Collossal was installed |

`collossal install` puts them in `~/.claude/settings.json` for every project. To
set them up by hand instead, merge `hooks.example.json` there, or into one
project's `.claude/settings.json` to scope them to that repo — but not both, or
that project's sessions are streamed twice.

### How a session becomes memory

The worker reads from the last cursor, then looks for four mechanically
detectable moments — nothing here calls a model:

- **`FAILURE_FIX`** — a command failed, edits followed, the same command passed.
  Matched on command *shape* rather than exact text, because an agent re-runs
  the same tool against a different file rather than retyping the failure.
- **`REVERSAL`** — one file rewritten six or more times, with the reasoning
  stated nearest the final edit. Fewer than six is ordinary iteration.
- **`USER_CORRECTION`** — the user pushed back right after an assistant action.
- **`STATED_CONSTRAINT`** — the user stated a rule.

A session reaching none of these is dropped having cost one file read. Measured
across 78 real transcripts (296 MB), that gate discards 39% for free and the
rest yield about 6 windows each.

Windows are stored separately from decisions, so the store of durable claims
never fills with unprocessed transcript fragments. A stub promotes `FAILURE_FIX`
windows to decisions at confidence 0.4; injection ignores anything below 0.5, so
raw machine guesses never reach an agent's context before distillation exists.

### Redaction

Credentials are stripped in the worker, immediately before the push — not on
the server, because scanning there would still mean the secret crossed the
network and landed in a request log.

Three layers: known vendor formats (Anthropic, OpenAI, GitHub, AWS, Slack,
Google, Stripe, JWTs, private keys, connection strings), assignments whose
*name* claims to hold a credential (`API_KEY=`, `SECRET=`), and a Shannon
entropy fallback for credentials with no recognisable shape.

The trade is deliberately asymmetric: a false positive costs a slightly less
readable memory, a false negative puts a live credential in a database forever.

Measured against 564 fields from real transcripts: **zero false positives**,
and zero secrets missed across a suite of 15 credential formats. Absolute paths
are rewritten repo-relative in the same pass, so memory does not carry one
machine's directory layout to everyone else.

### Safety properties

The hook always exits 0 and swallows every error to `~/.collossal/hook.log`. It
cannot fail a session, and with the API unreachable a session starts normally
with no memory rather than an error.

## Live sessions

A workspace admin can watch a session as it happens and step into it.

| Piece | Does |
|---|---|
| `tailer.py` | Spawned at SessionStart, detached. Follows the transcript, redacts, and pushes render-ready events plus snapshots of uncommitted work — `git diff`, and files not yet added — which a session's Changes tab and the workspace owner's Code diff view show. An empty snapshot means the tree is clean again. |
| `Stop` hook | Collects instructions queued from the dashboard and hands them to the agent as its next input. |

Two properties worth knowing.

**It tails, it does not replay.** The tailer starts from the current end of the
transcript. A hook firing on a resumed session would otherwise push its entire
history — megabytes — as though it had all just happened.

**Instructions arrive at a turn boundary, not instantly.** There is no way to
interrupt a turn already running, so anything sent is queued and delivered the
moment the agent would otherwise have stopped. Delivered exactly once: a
repeated instruction would have the agent redo work.

Everything streamed is redacted on the machine first, and absolute paths are
rewritten repo-relative — a watcher sees the repository, not someone's home
directory. Events are kept for `SESSION_RETENTION_DAYS` (90 days by default),
so a session can be read back after it ends; the durable record of a session
remains the decisions distilled from it.

Sending an instruction also writes a `NOTICE` into the stream the watched
person can see. Being observed and redirected with no indication of it is not
something to ship.

## Layout

```
config.py       env, validated once at startup
git_context.py  repo/branch/commit discovery and path normalisation
client.py       Collossal API client
format.py       renders decisions for a context window
server.py       MCPServer and the tools
capture/
  hook.py       lifecycle hook: injection, and spawning the worker
  worker.py     detached — reads transcript, gates, ships
  transcript.py streaming JSONL reader
  windows.py    the four detectors
  redact.py     strips credentials before anything leaves the machine
  ship.py       API calls for capture and injection
```
