Model Context Protocol

Configuration

If there is a ~/.cursor folder when the Uclusion install script runs it will add itself to the mcp.json there using the installed proxy script and your workspace ID:

{
  "mcpServers": {
    "Uclusion": {
      "command": "python3",
      "args": [
        "/usr/local/bin/uclusionMCPProxy.py",
        "dd56682c-9920-417b-be46-7a30d41bc905"
      ]
    }
  }
}

The install script will do the same adding of a Uclusion mcp server to the ~/.claude.json if it is present.

For Codex (OpenAI) the config file is TOML, so if a ~/.codex directory is present the install script adds an equivalent [mcp_servers.Uclusion] table to ~/.codex/config.toml:

[mcp_servers.Uclusion]
command = "python3"
args = [
    "/usr/local/bin/uclusionMCPProxy.py",
    "dd56682c-9920-417b-be46-7a30d41bc905",
]

Unlike Cursor and Claude Code — whose config files are created automatically on first run — Codex treats config.toml as optional, so the install keys off the ~/.codex directory existing rather than the file. The managed table is delimited by # uclusion-mcp:v1 comment markers, so a later install refreshes it in place and the rest of your config.toml is left untouched. The Codex CLI runs on macOS, Windows, and Linux; only the Codex desktop app is macOS/Windows only.

Per-job token usage notes

The setup page can optionally enable Token usage notes for Claude Code and Codex. It is off by default. When enabled, the workflow starts one audit run for an active job, marks boundaries between kinds of work, and finishes the run at a blocker, review handoff, or completion. Planning, implementation, testing, and other are the default boundary labels, but a user can ask the agent to use labels suited to the job instead—for example, web searches, source review, and copywriting. One label applies to each model request, so the labeled totals reconcile to the run total without counting a request twice.

The result is added to the job as a consistent, export-readable usage note with the run total and its labeled breakdown when the client exposes enough information. There is no separate server-side token-reporting database or analytics dashboard; the collector’s local delivery state is temporary. When you ask for cumulative or cross-job statistics, the AI reads these notes from the workspace export and calculates the requested view. Collection begins at the explicit audit start, so earlier turns are excluded; missing events inside that audit window or an interrupted client are labeled as partial rather than presented as complete measurements.

Each boundary also publishes a cumulative checkpoint after the usage for the bucket that just closed becomes available. The checkpoint includes every completed bucket through its marker sequence and names the new bucket as open; usage in that open interval is not included yet. Checkpoint delivery depends on the audit boundary and telemetry, not on the job moving to Reviewable, a CI run, or a deployment. Ending the audit closes and publishes the final bucket as the terminal snapshot.

Uclusion may update a clearly matching checkpoint or add another ordinary usage note. When several notes have the same audit-run UUID, they are cumulative snapshots rather than amounts to add together: use the terminal snapshot when present, otherwise the checkpoint with the highest marker sequence. This lets an interrupted run retain every bucket that had already closed; only the bucket that was still open at the interruption can be absent or partial.

The copied setup command contains an explicit --token-audit or --no-token-audit flag. After installation, you can enable token usage notes from the terminal while updating Uclusion and its installed client surfaces:

uclusion update --token-audit

Disable them and remove Uclusion-owned client settings with:

uclusion update --no-token-audit

For a non-production environment, put its option before the subcommand—for example, uclusion -e stage update --token-audit. The update covers the global install plus a project install in the current directory, when present; run it from the project root when you also want that local install changed. Omitting both flags preserves each install’s existing preference. Restart the affected AI client sessions (or reconnect their Uclusion MCP servers) after the command completes so the new setting loads.

Disabling the feature removes only the Claude settings and hooks previously written by Uclusion; unrelated hooks and user-edited telemetry values remain. Locally delivered checkpoint and final rows are removed seven days after successful delivery. If a checkpoint or run cannot be delivered, or a run never reaches a handoff, its allowlisted local data is retained for recovery for at most 30 days from audit start. Ordinary Uclusion MCP launches apply that scoped cleanup even while token notes are disabled.

For Claude Code, Uclusion first tries Claude’s local OpenTelemetry log stream over HTTP/JSON. The installer configures logs only, binds the receiver to localhost, and explicitly turns off prompt, response, tool-content, and raw API body logging. If Claude settings already contain a non-Uclusion telemetry or content policy, the installer preserves it and uses the local transcript as a fallback. That choice is made during installation; Uclusion does not silently switch a running OpenTelemetry audit to transcript collection if its receiver later becomes unavailable. Such a run is reported as partial or unavailable.

Transcript fallback incrementally reads only recognized Claude Code v2 usage records after a lifecycle hook identifies the session. It can be less complete than OpenTelemetry after client upgrades, compaction, interrupted sessions, or incomplete subagent coverage. Unsupported or identifier-less records therefore degrade coverage instead of being presented as an exact measurement. Token counts and user-selected boundary totals are recorded; prompt and response text are not copied into the job note.

Both collection modes require Claude lifecycle hooks and an exact matcher for the three Uclusion audit marker tools. If Claude settings contain "disableAllHooks": true, the installer leaves that preference untouched, warns that Claude auditing was not enabled, and registers ordinary Uclusion MCP access without the audit tools. Remove the setting (or change it to false), rerun setup, and restart Claude Code to enable token notes.

For Codex, token collection is part of the private app-server bridge created by uclusion codex. A normal codex launch can still use the Uclusion MCP table installed in ~/.codex/config.toml, but it does not expose the audited MCP tools or provide the bridge’s usage events. Launch each session whose jobs you want measured with uclusion codex; setup cannot retrofit collection onto an already-running Codex process.

The preference is stored under tokenAudit in the workspace’s uclusion.json (or environment-prefixed/project equivalent), together with a stable local receiver port. Setup installs the collector alongside the matching proxy release, adds Claude’s audit arguments only when its hooks are usable, and leaves Codex audit arguments to the uclusion codex launcher. Restart Claude Code (or reconnect its MCP server) after changing the option; start a new uclusion codex session for Codex. Collection begins when the workflow calls start_job_audit and does not retroactively count earlier turns.

Workflow rule files

The install script also offers to drop a workflow rule file in the spot each AI client looks for it. Both prompts default to N, and a subsequent install will offer to refresh in place (the Uclusion-managed block is delimited by <!-- uclusion-workflow:v1 --> markers so nothing else you’ve added to the file is touched).

• Claude Code: appends or refreshes the workflow block in ~/.claude/CLAUDE.md.
• Cursor: writes ~/.cursor/rules/uclusion.mdc as a description:-based Cursor rule that loads whenever the prompt references a Uclusion short code (J-*, T-*, B-*).
• Codex: appends or refreshes the workflow block in ~/.codex/AGENTS.md (offered only when the ~/.codex directory exists).

Both files contain the same step-by-step Uclusion job workflow — read the job, ask questions in Uclusion, make suggestions, approve, execute, and ask for review — so the AI keeps its planning, questions, and progress reports in the job instead of in chat scrollback.

Using find_work

You can mark jobs, bugs, or discussion as “AI able” and when your agent uses the find_work tool those items will be listed as options to begin.

A view can also opt into AI agents take the next available work from this view without asking. Work from an opted-in view has auto_take: true in the find_work response. When the agent is idle, it still presents the complete list but calls get_job for the first marked item in the same turn; merely announcing a start and then going idle is not enough. Unmarked items are never auto-started, active work is never interrupted, and a direct human instruction takes precedence. The item’s stage and the normal read, question, suggestion, approval, execution, and review workflow continue to apply.

The durability rule follows the auto-taken item for its entire active work lane. Before the initial auto-take turn or any later turn working that item ends, its material handoff must be durable in Uclusion. The agent uses the specialized MCP action for questions, suggestions, approvals, resolutions, and review requests, and uses add_info on the active item for other substantive results, blockers, or next steps. Chat may mirror that handoff, but cannot be its only copy. Auto-take begins only inside an existing agent turn; it does not wake or launch an idle client. The Views documentation explains where to enable it.

Poking your AI

The proxy also delivers prompts from Uclusion to your connected terminal — Poke AI buttons send Start <short code>. Once AI has participated in a job, creating response-worthy work sends Added <short code>, while edits, moves, deletions, assignment changes, description changes, and explicit stage changes send Updated <short code>. Answering the AI’s last open item or handing a task or note thread back after its latest turn sends Responded <short code>. Items inside a question’s option append the enclosing question, for example Added C-1 of Q-all-556, because their short codes are local to the question’s inline decision market. Added and Updated events augment the active work rather than replace it; Start is reserved for a human explicitly pressing Poke AI. See Poke AI for the buttons, the message forms, how the local prompt queue works, and what running multiple agents requires.

Recalling past decisions

Chat scrollback evaporates when a context window clears, but every question, option, vote, and reason in your workspace persists. The workflow rule files tell the AI that before re-opening a settled debate — or whenever it needs to know if something was already decided — it should run uclusion export in the shell and search the resulting markdown. Because the AI holds the full contents locally, found items display with their details right in the conversation — you drill into results there and follow a short code into Uclusion only when you want the live object. The export is incremental, so refreshing it before a lookup costs seconds, and a fresh session (or a different AI entirely) recalls decisions it was never part of making.

Starting a session on find_work

A rule file can only influence a turn the AI is already taking, nothing in it makes the AI act before you send a first message. The reliable way to open a session straight into find_work is to make that the first message yourself, which both CLIs let you do as a launch argument:

• Claude Code pre-fills the prompt into the input box, so you press Enter to send it:

  claude "Run find_work"
  

• Codex takes the prompt as the initial task and starts on it immediately — no Enter needed:

  codex "Run find_work"
  

Wrap whichever you use in a shell alias so it becomes your normal way in:

alias uc='claude "Run find_work"'      # Claude Code
alias ux='codex "Run find_work"'       # Codex

Now uc (then Enter) or ux opens the AI with find_work already requested, and it answers with your numbered list of options. (Cursor is an editor rather than a prompt-on-launch CLI, so there is no equivalent there — its rule file still triggers find_work once you ask the AI to start.)

Tools

Your client loads tool definitions from the server; the Uclusion MCP server currently exposes these tools:

These tools allow you to write a prompt like this:

Use Uclusion to get J-all-284 and also read through the application documentation at https://some.documentation.com. Then as a product manager use Uclusion to ask any questions you have about the business value of this job before adding an approval

Context Preservation

Resolved comments have only 80 characters includes in the get_job markdown. include_all_resolved can be passed by AI to get the complete markdown including everything.

Notes are NOT included by default unless the note has a reply. You can use the ‘Show AI’ checkbox to force a notes inclusion by get_job.

The AI keeps its own standing guidance the same way: the add_view_note tool saves a general lesson as a ‘Show AI’ view note - notifying the view on every create or modify - instead of private agent memory. See view level notes.

Basic Flow

Read the installed rules file for the complete flow. Here is a summary:

1. Read the job. If possible read documentation and other resources explaining the software.
2. Ask questions. Resolve questions that you feel have been answered.
3. Make suggestions.
4. Approve the job with some level of certainty and reason that it is worth doing. Feel free to give a low certainty if the job is not well designed or providing value for customers.
5. When instructed to start on a task and that task’s grouped tasks. Resolve tasks that you feel are complete. Use the add_info tool at the job or task level if people need to know something important about your implementation.
6. If you complete a set of tasks that then has a testable output, use the ask_for_review tool to ask for feedback.

Note that most Uclusion notifications resulting from AI user actions are muted in favor AI’s own notification channel.

Reviewing and clearing notifications

Your own inbox for a workspace is also reachable from the terminal: ask what needs your attention and the agent calls get_notifications, which renders your notifications as markdown — most urgent first, each with the short code it is about. When the agent finishes work on something it offers to clear that object’s remaining notifications, asking first exactly like it asks before committing. Clearing follows the same rule as the web application: unread notifications are removed while persistent ones only lose their highlight. There is deliberately no clear-everything operation — a whole-inbox wipe could silently discard notifications that arrived after you granted the permission.

Knowing when to clear

As your AI client works it accumulates context — the job or comment Markdown returned by MCP and all files touched etc. None of that goes away on its own. The AI cannot reset its own context, so it will not start fresh between pieces of work unless you tell it to (in Claude Code, /clear).

The only automatic mechanism is compaction near the context limit, which summarizes older history rather than clearing it — that is lossy and leaves stale work resident until the limit is reached, so it is a safety net, not a clean handoff. Issue a /clear yourself at natural boundaries instead of relying on it.

The right boundary depends on which workflow you are in:

• Single comment workflow (a view level bug or question comment). Each comment is normally self-contained and you are done after resolve. If you hand the AI a series of unrelated comments, clear between them: the previous comment’s files and decisions are irrelevant to the next one, and clearing keeps cost down and prevents the AI from conflating them. If several comments touch the same area of code, keep the context so the already-read files stay warm and the AI does not re-read them.

• Job workflow (anything job or comment within a job will load the whole job). Keep the context for the life of a job — the questions, suggestions, approvals, and progress reports build on each other across steps, and clearing mid-job throws away the thread the AI is working from. Because every artifact is written back into Uclusion, though, a fresh session can reload the whole plan, so it is safe to clear between jobs after a job’s work is complete and reviewed.

You do not have to keep these boundaries in your head: the installed rules file tells the AI to offer a clear at exactly these moments — after resolving a view-level comment when the next item may be unrelated, and after a job’s work is complete and reviewed — and to stay quiet mid-job or when consecutive comments share the same area of code. Treat the offer as a reminder, not a requirement: you can still clear whenever you like, and declining costs nothing.