NoFray Agent Plugin
Use NoFray from a compatible AI agent to manage tasks, projects, and contacts, including their notes, and extract grounded tasks from client-held transcripts. The plugin combines:
- the local NoFray MCP server at
http://127.0.0.1:7341/mcp; - read-only meeting search, meeting bundles, and bounded meeting-document
reads through
nofray_search_meetings,nofray_get_meeting, andnofray_get_meeting_document; - a NoFray management skill that recognizes tasks and action items, as well as direct Project/Contact work such as project notes and contact details;
- a client-side transcript workflow: source-grounded task intent stays with the client while NoFray provides canonical task discovery, review and the proposal/apply/read-back route;
- the v2 NoFray proposal workflow for ordinary writes.
Codex surfaces use the bundled NoFray logo and brand color from the native
.codex-plugin presentation manifest. These visual assets do not alter skill
activation or MCP behavior.
Because the MCP server runs inside the NoFray macOS app, this is a desktop-only plugin. NoFray and the AI client must run on the same Mac.
Tasks, Projects, and Contacts are independently searchable and readable.
Projects and Contacts can be created, updated, archived, restored, or deleted
through the live V2 proposal workflow. Task details and Project/Contact
notes are canonical Markdown bodies sent as string values; Markdown text such
as headings, lists, and links is accepted directly. For notes, set replaces
the full body, clear removes it, and omission leaves it unchanged. A Project
or Contact can be created or updated without a linked task. Additions to notes
preserve the existing body by proposing its full updated value. Project edits
require the live canRenameProjects capability; Contact edits require
canEditContacts.
The live task search can select native lists, completion/archive state and exact
field values while returning query coverage. Archive, restore and delete use
archiveRecord, unarchiveRecord and deleteRecord through the existing V2
proposal tools when advertised. NoFray's application services own their effects
and reference safety. Discovery exposes the shared task-field information;
clients may reuse sufficient enum IDs rather than rediscovering them per task.
Requirements
- NoFray installed on macOS.
- A workspace mounted in NoFray.
- A client that supports Agent Plugins 1.0 skills and Streamable HTTP MCP.
- Port
7341available on the Mac.
Contract version
This release uses the v2 MCP contract for its mutation surface. A client must
discover the mounted workspace before every mutation session and require the
live recordMutationContractV2 and
recordMutationV2 capabilities, plus recordReferenceCandidatesV2 when it
resolves relations. The client uses the schemas returned by
nofray_get_workspace_configuration. The plugin does not fall back to a
legacy request envelope when a capability is absent.
When live discovery advertises meetingRead, meeting questions use the three
read-only meeting routes. Search first, read one meeting with meetingOnly as
the default scope, and fetch a named document only when its role or document
ID is known. The response context and coverage belong to one workspace
generation. Transcript results contain metadata and availability; they do not
expose transcript bodies.
Also check the action-specific capabilities returned by discovery. They
describe the implemented MCP routes admitted by the current workspace.
A field in the schema does not grant write permission. Complete or reopen a task
through the existing updateRecord route by setting its configured status;
check canComplete, canEdit and the live field contract. NoFray derives the
completion date, advances recurrence and synchronizes linked minutes checkboxes.
Send the requested status and report the canonical result, which may be the
active next occurrence. Preserve typed lifecycle restrictions.
For a change set, check the permissions for each
project/contact create and each relation change as well as the task operation.
Standalone project/contact operations use recordType: "project" or
recordType: "contact" in an ordinary single-record proposal; they do not use
the task dependency change-set route.
Mutation field operations are exact and sparse:
{
"operation": "set",
"value": "2026-09-30T17:00:00+02:00"
}
Use { "operation": "clear" } without a value to clear a field; omit a
field to leave it unchanged. The root request's context object must carry the
same discovered workspaceID, sessionID, generation, schemaDigest, and
capabilityDigest. The recurrence value retains its canonical storage
version: 1 member inside the recurrence object; that is separate from the
v2 MCP envelope.
When the live proposal tool schema advertises Inbox actions, explicit Inbox
membership uses the same proposal/resolve/apply tools:
request: {"action":"addToInbox","recordType":"task","recordID":"<task ID>"}
or action: "clearInbox", with the discovered context and no generic
fields. inboxAddedAt remains lifecycle-only. Automatic MCP create
admission is separate: when enabled in the live workspace settings, every new
MCP task enters the Inbox, including tasks with projects, tags, contexts or
assignees and tasks created through a change set. Check canonical readback for
membership; updates and duplicate reuse do not automatically enter the Inbox.
Apply returns canonical readback verified against the writer's record ID and
revision. An error with writeState: "committed" and
verificationStatus: "unverified" includes the known operation/record ID,
revision and a bounded reason. Follow recoveryAction: "repeatApply" by
resubmitting unchanged apply arguments: this verifies the existing receipt
without writing again, even after generation advances. Do not create another
record. If verification remains unavailable, inspect the returned record ID.
Receipts are caller/session/token-bound and kept in a bounded in-memory cache
for up to ten minutes. An already verified receipt retains evidence of the
original operation; use get-record tools to inspect subsequent changes.
writeState: "unknown" requires inspection before any retry that could
create a record. notAttempted describes the current invocation only.
New writes still reject stale generation/context with refreshProposal;
discover fresh context and obtain a new server-authored preview/resolution.
The live capability contract may be narrower than the app-owned record
contract. Typed
collection fields (aliases, tags, contexts, assignees, projects (legacy: projectLinks),
reminders, methods, and affiliations) do not accept set with null:
use set with an empty array for an empty collection or clear to remove the
field. Optional temporal and recurrence values accept null only when the
discovered field contract advertises it. The client must use the advertised
allowsNull value and verify the canonical readback.
Projects can expose tags, scheduled, and due, while contacts can expose
tags; their availability and exact schema are returned by discovery. A
missing named field reported in unavailableFields is a source-health warning,
not an authored empty value, and must remain visible until an explicit repair.
When discovery also advertises recordMutationChangeSetV2, the same proposal
tools accept request.action: "changeSet" for exactly one Task operation
(create or update), plus optional Project and Contact creates. The total is at
most 16 operations, so at most 15 dependency creates may accompany the Task.
Each create has a localReference; the Task update uses a target recordID.
Preview rejects multiple Task operations, Project or Contact updates,
unsupported record types, invalid relation types, cycles, and graphs outside
this one-Task-plus-dependencies shape before any write. Resolve duplicate
choices in a choices dictionary keyed by operation ID, using createNew or
useExisting with the server candidate ID. Apply the returned resolution
unchanged and read back every affected record.
Prepare NoFray
- Open NoFray and mount the workspace the agent should use.
- Open Settings > MCP.
- Enable Enable local MCP server.
- Keep the port at
7341. - Leave Require authentication off for the portable plugin setup.
- Select Test connection and confirm that the tool count is shown.
With authentication disabled, NoFray still listens only on 127.0.0.1 and
continues to enforce Host validation, Origin validation, request-size limits,
and rate limits. Other applications running on the same Mac can nevertheless
reach the server while it is enabled. Turn the server off when it is not
needed, or use the authenticated setup described below.
Install in Codex CLI
Add this repository as a plugin marketplace:
codex plugin marketplace add yvos/nofray-plugin-marketplace
Install the NoFray plugin from that marketplace:
codex plugin add nofray@nofray-marketplace
Confirm that it is installed:
codex plugin list
Restart or refresh Codex if the newly installed plugin is not visible in an already open session.
Install in Claude Code
Add this repository as a Claude Code plugin marketplace:
claude plugin marketplace add yvos/nofray-plugin-marketplace
Turn on automatic updates for the marketplace. Claude Code leaves them off for
third-party marketplaces, and its install commands have no option to enable
them. The command below sets autoUpdate on the marketplace entry that the
previous step added to your user settings, which is the same setting as
Enable auto-update under /plugin > Marketplaces:
settings="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/settings.json" && jq '.extraKnownMarketplaces["nofray-marketplace"].autoUpdate = true' "$settings" > "$settings.tmp" && mv "$settings.tmp" "$settings"
Claude Code then refreshes the marketplace in the background after a session starts and updates NoFray when a new version is published. A running session keeps the version it loaded until you start a new one.
Install the NoFray plugin:
claude plugin install nofray@nofray-marketplace
Confirm that it is installed:
claude plugin list
Start a new Claude Code session. If installing from inside an existing session,
run /reload-plugins when Claude Code asks you to activate the new plugin. Use
/mcp to confirm that the plugin-provided nofray server is connected.
Install in ChatGPT or a managed Codex workspace
A workspace administrator can import the marketplace from GitHub:
- Open Workspace settings > Plugins.
- Select Add > Import marketplace.
- Enter
https://github.com/yvos/nofray-plugin-marketplaceas Source. - Leave Path empty because
.agents/plugins/marketplace.jsonis at the repository root. - Use
mainas the branch, or leave the branch empty to follow the default. - Import the marketplace and review the result.
- Open the NoFray plugin and choose the appropriate installation policy.
- Install or enable it for the intended users or roles.
The MCP declaration makes the imported plugin desktop-only. It cannot reach a NoFray server running on a different Mac or from ChatGPT on the web.
Install in another compatible client
Load the AgentPlugin directory as an Agent Plugins 1.0 package using the
client's documented local-directory or repository installation flow. The
client must support both Agent Skills and the streamable-http MCP transport
to provide the full NoFray experience.
The current compatibility list is maintained at https://agent-plugins.org/compatible-clients.
Verify the complete connection
After installation, start a new agent session and ask:
Show my open action items in NoFray.
A working installation should let the agent discover the NoFray tools, read
the workspace configuration and live recordMutationContractV2 capability,
list canonical field values when needed, and search tasks. For a write test,
explicitly ask it to create a disposable task or a disposable Project with a
short notes paragraph; the agent should pass the v2
context-bound request through the proposal, resolution, and apply tools in
sequence, then verify the canonical readback.
For a transcript-derived task test, keep the original source and its interpretation in the client. Extract source-grounded actionable intent and explicit existing-task changes there, preserving source references and uncertainty. Use NoFray only for canonical task/project/contact discovery and the authorized proposal, resolve, apply and read-back workflow. The MCP surface does not accept transcript text or generate meeting minutes.
For a meeting-read test, ask:
Find the meeting about quarterly planning and list its current open and completed tasks.
The agent should call nofray_search_meetings, use the returned meeting ID in
nofray_get_meeting with an explicit task filter when needed, and preserve
missingTaskIDs, document coverage, provenance, and the response context. To
read a body, it should call nofray_get_meeting_document with exactly one role
or document ID and follow a revision-bound cursor for large content.
Authentication
The portable plugin deliberately contains no bearer token. Do not add a token
to mcp.json, commit one to the repository, or paste one into SKILL.md.
To require authentication:
- Enable Require authentication in NoFray > Settings > MCP.
- Select Connect AI Client….
- Choose the client and use the generated client-specific setup command.
- Disable or override the plugin-provided credential-free MCP entry if the client would otherwise try both connections.
The bundled skills remain useful, but the portable mcp.json entry
cannot authenticate by itself. Token storage and header configuration must be
handled by the client.
Custom port
The distributed plugin targets port 7341. Keeping this port is the simplest
and recommended setup. If another process occupies it, either:
- choose another port in NoFray and configure the MCP endpoint directly with Connect AI Client…; or
- maintain a private copy of the plugin and change the URL in
mcp.jsonto the same port.
The port in NoFray and the port in the client configuration must match.
Update or remove in Codex CLI
Codex refreshes configured Git marketplaces, and the plugins installed from them, in the background when it starts; no setting is needed. To update right away, refresh the Git marketplace; Codex then reinstalls the plugin from the new snapshot:
codex plugin marketplace upgrade nofray-marketplace
codex plugin list
Remove the plugin with:
codex plugin remove nofray@nofray-marketplace
Remove the marketplace separately only when it is no longer used by any installed plugin.
Update or remove in Claude Code
With automatic updates turned on during installation, Claude Code does this in the background. To update right away, refresh the marketplace and update the installed plugin:
claude plugin marketplace update nofray-marketplace
claude plugin update nofray@nofray-marketplace
Restart Claude Code to use the updated plugin. Remove the plugin with:
claude plugin uninstall nofray@nofray-marketplace
The interactive equivalents are available through /plugin. Removing the
marketplace itself also uninstalls plugins installed from it.
Troubleshooting
The plugin is installed but no NoFray tools are available
- Confirm that NoFray is running and a workspace is mounted.
- Confirm that the MCP server is enabled.
- Confirm that NoFray and the agent client run on the same Mac.
- Confirm that both sides use port
7341. - Run Test connection in NoFray.
- Start a fresh agent session after installing or updating the plugin.
- Check whether the client supports Streamable HTTP MCP in Agent Plugins.
- In Claude Code, run
/mcpand/reload-pluginsto inspect and reload the plugin-provided connection.
The connection is unauthorized
Authentication is enabled in NoFray, but the portable plugin has no token. Either disable authentication for the loopback-only setup or configure the client through Connect AI Client….
The connection is refused or lost
- Toggle the local MCP server off and on in NoFray.
- Check that another process is not using the configured port.
- Review the MCP diagnostics in NoFray's logs.
- Retry from a new client session after the server reports that it is running.
Read calls work but writes do not
NoFray writes use the v2 request and require all three server-owned steps:
nofray_create_change_proposalnofray_resolve_change_proposalnofray_apply_change_proposal
The agent must pass server-authored IDs, generations, hashes, and resolutions
unchanged, together with the discovered workspace/session and schema and
capability digests. It must also use canonical status and priority IDs returned
by nofray_list_field_values, and verify each applied record using apply's canonical
readback. Use get-record tools only for missing evidence or later current-state reads.
Package layout
AgentPlugin/
├── .codex-plugin/
│ └── plugin.json
├── .claude-plugin/
│ └── plugin.json
├── .mcp.json
├── assets/
│ ├── composer-icon.svg
│ └── logo.svg
├── plugin.json
├── mcp.json
├── README.md
├── CHANGELOG.md
└── skills/
└── nofray-task-management/
└── SKILL.md
The repository-level .agents/plugins/marketplace.json makes this package
installable as a Codex marketplace entry. The repository-level
.claude-plugin/marketplace.json, plugin manifest, and .mcp.json provide the
native Claude Code installation route. Installation, permissions, updates, and
enablement remain controlled by the client.
Specifications
- Agent Plugins 1.0: https://agent-plugins.org/specification
- Agent Skills: https://agentskills.io/specification
- Model Context Protocol: https://modelcontextprotocol.io/specification