Codex++ Project Home

Adds a hover-only home icon to Codex project rows. Clicking it, or pressing Cmd+Shift+H from a project thread, opens a Project Home view for that project.

V1 includes a per-project kanban board for Linear-style issues:

• Columns: Backlog, Todo, In Progress, In Review, Done
• Create issues from the board or a column header
• Drag issues between columns
• Right-click or use the issue ellipsis menu to edit, move, or delete
• Issues are stored in a JSON DB keyed by project path

The tweak also includes mcp-server.js, a stdio MCP server backed by the same issue store. Tools:

• project_home_help — self-documenting; pass tool: "<name>" for focused help
• project_home_columns
• project_home_list_issues
• project_home_search_issues
• project_home_get_issue
• project_home_create_issue
• project_home_update_issue
• project_home_add_comment
• project_home_move_issue
• project_home_delete_issue
• project_home_linear_sync

Agents unfamiliar with the server can call project_home_help (no arguments) to discover available tools, status/priority enums, and the author: "Codex" convention.

Issue ids use a per-project prefix derived from the first 2–3 alphanumeric characters of the project folder name (e.g. issues under …/tweaks/ become TWE-1, TWE-2, …). Existing PH-* ids are preserved.

Comments support an author field. The MCP exposes it on project_home_add_comment (author) and on project_home_create_issue / project_home_update_issue (newCommentAuthor). The board renders author · timestamp when present. Agents should pass author: "Codex" when leaving notes.

Registering the MCP with Codex

Codex++ does not currently forward manifest.json#mcp into Codex's own MCP runtime, so the agent will not see these tools until you register the server manually. Add this block to ~/.codex/config.toml and restart Codex:

[mcp_servers.project-home]
command = "node"
args = ["/ABSOLUTE/PATH/TO/codex-plusplus/tweaks/co.bennett.project-home/mcp-server.js"]

On macOS the absolute path is typically /Users/<you>/Library/Application Support/codex-plusplus/tweaks/co.bennett.project-home/mcp-server.js.

To verify, ask Codex "what MCPs can you see?" — project-home should appear with the project_home_* tools. Once upstream Codex++ auto-registers MCP entries from tweak manifests, this manual step can go away.

Linear sync

project_home_linear_sync pushes Project Home issues to Linear through Linear's GraphQL API. Set:

export LINEAR_API_KEY="lin_api_..."
export LINEAR_TEAM_ID="<team uuid>" # optional; first accessible team is used when omitted

Then call the MCP tool with projectPath. Pass issueId to sync one issue or omit it to sync all issues in the project. Pass dryRun: true to preview creates/updates without writing to Linear or local issue metadata.

After a successful write, the local issue stores linear.id, linear.identifier, linear.url, and linear.syncedAt. Later syncs update that Linear issue instead of creating a duplicate.

You can also open Codex++ Settings > Project Home and save the Linear sync config per project. The settings page stores the required apiKey plus optional teamId, apiUrl, and default sync mode in the same per-project Project Home DB used by the MCP server. It includes a link to Linear API settings for creating a personal API key and choosing team access.

Note: Codex's Rust MCP transport speaks newline-delimited JSON (NDJSON) on stdio, not LSP-style Content-Length framing. mcp-server.js writes one JSON message per line accordingly.

One-shot install via Codex

Don't want to edit TOML by hand? Open a Codex chat and paste the block below. Codex will locate the MCP server, add the [mcp_servers.project-home] entry to ~/.codex/config.toml (idempotently), verify the server boots, and tell you to restart Codex.

Install the project-home MCP for me. Steps, in order:

1. Resolve the absolute path to `mcp-server.js` for the project-home tweak. On macOS this is:
   `/Users/$USER/Library/Application Support/codex-plusplus/tweaks/co.bennett.project-home/mcp-server.js`
   On Linux: `${XDG_DATA_HOME:-$HOME/.local/share}/codex-plusplus/tweaks/co.bennett.project-home/mcp-server.js`
   Confirm the file exists with `ls -la` before continuing.

2. Read `~/.codex/config.toml`. If a `[mcp_servers.project-home]` block already exists with the
   correct `command` and `args`, do nothing and skip to step 4. Otherwise, back the file up to
   `~/.codex/config.toml.bak.$(date +%s)` and append:

   ```toml
   [mcp_servers.project-home]
   command = "node"
   args = ["<absolute path from step 1>"]
   ```

3. Run `codex mcp list` (path: `/Applications/Codex.app/Contents/Resources/codex` on macOS) and
   confirm `project-home` shows up as `enabled`.

4. Smoke-test the server by running it directly and sending an `initialize` request over stdio
   using newline-delimited JSON (NDJSON). The server must respond with `serverInfo.name = "project-home"`.
   Example one-liner:

   ```bash
   node -e '
     const {spawn}=require("child_process");
     const c=spawn("node",["<path>"]);
     c.stdin.write(JSON.stringify({jsonrpc:"2.0",id:1,method:"initialize",params:{protocolVersion:"2024-11-05"}})+"\n");
     let out=""; c.stdout.on("data",d=>{out+=d; if(out.includes("project-home")){console.log("OK"); c.kill(); process.exit(0)}});
     setTimeout(()=>{console.log("FAIL",out); c.kill(); process.exit(1)},2000);
   '
   ```

5. Report back with: the path you used, whether the config was already present or newly added,
   the backup filename (if any), and a one-line confirmation that `initialize` returned `OK`.
   Then tell me to fully quit and reopen Codex (Cmd+Q on macOS) so the new MCP is picked up.

If anything fails, stop and show me the exact error rather than guessing. Do not modify any
other section of `config.toml`.

After the restart, ask Codex "what MCPs can you see?" — project_home should appear in the list.

Tests

npm test

Runs tests/mcp.test.js, an end-to-end smoke test that spawns mcp-server.js, drives every tool over stdio (NDJSON JSON-RPC), and asserts the MCP issue and Linear sync paths. The test uses CODEX_PLUSPLUS_DATA_DIR to point at a temp directory, so your real issue DB is never touched. No external dependencies — Node >= 18 is enough.