collossal 0.1.0__tar.gz

collossal-0.1.0/PKG-INFO

@@ -0,0 +1,218 @@
+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
+```

collossal-0.1.0/README.md

@@ -0,0 +1,206 @@
+# 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
+```

collossal-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[project]
+name = "collossal"
+version = "0.1.0"
+description = "Collossal CLI: connects your coding agent to your team's sessions, memory and rooms."
+readme = "README.md"
+requires-python = ">=3.14"
+dependencies = [
+    "mcp[cli]>=2.2.0",
+    "httpx2>=2.12.0",
+    "websockets>=13.0",
+]
+
+[[project.authors]]
+name = "Vipul"
+email = "vilulgupta2802@gmail.com"
+
+[project.scripts]
+collossal = "main_mcp.cli:main"
+collossal-mcp = "main_mcp.server:main"
+collossal-hook = "main_mcp.capture.hook:main"
+
+[build-system]
+requires = ["uv_build>=0.12.12,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "main_mcp"

collossal-0.1.0/pyproject.toml.orig

@@ -0,0 +1,31 @@
+[project]
+name = "collossal"
+version = "0.1.0"
+description = "Collossal CLI: connects your coding agent to your team's sessions, memory and rooms."
+readme = "README.md"
+authors = [
+    { name = "Vipul", email = "vilulgupta2802@gmail.com" }
+]
+requires-python = ">=3.14"
+dependencies = [
+    "mcp[cli]>=2.2.0",
+    # Used directly by the API client. It arrives transitively via mcp, but a
+    # direct import needs a direct declaration.
+    "httpx2>=2.12.0",
+    # `collossal room` streams its terminal to the room and takes keystrokes
+    # back; polling would make every keypress a round trip of a second or more.
+    "websockets>=13.0",
+]
+
+[project.scripts]
+collossal = "main_mcp.cli:main"
+collossal-mcp = "main_mcp.server:main"
+collossal-hook = "main_mcp.capture.hook:main"
+
+[build-system]
+requires = ["uv_build>=0.12.12,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+# The package is published as `collossal`; its code lives in `main_mcp`.
+module-name = "main_mcp"

collossal-0.1.0/src/main_mcp/__init__.py

@@ -0,0 +1,16 @@
+"""Collossal MCP server."""
+
+
+def main() -> None:
+    """Entry point.
+
+    The import is deferred so that `python -m main_mcp.server` does not load the
+    server module twice — which would run its startup config load and client
+    construction a second time.
+    """
+    from .server import main as run
+
+    run()
+
+
+__all__ = ["main"]