Connect an AI agent

Ideafy is only useful with an AI agent on the other end of the MCP. This page covers how to point Claude Code, Gemini CLI, or Codex CLI at Ideafy's MCP server inside your project. The same idea repeats per project — configuration lives per-project, not globally.

What you're configuring

Three things need to line up:

1. Ideafy's MCP server — a local process your agent talks to, exposing tools like save_plan, save_tests, pool_push
2. Bundled skills — ideafy.md, human-test.md, product-narrative.md — files the agent reads to know how to use the tools
3. A hook — a UserPromptSubmit hook that injects the current card ID into every prompt so the agent doesn't lose track

The project settings modal has a one-click Install button that does all three for you. The rest of this page explains what it writes and where, so you can debug it if something goes wrong.

One-click install

In the project settings modal, under MCP & Skills, click Install Ideafy. This writes:

• MCP server entry into .claude/settings.json (or .mcp.json for Gemini/Codex) in the project root
• Skills into .claude/skills/ideafy.md, .claude/skills/human-test.md, .claude/skills/product-narrative.md
• Hook into .claude/settings.json → hooks.UserPromptSubmit — injects a system reminder whenever the IDEAFY_CARD_ID environment variable is set

The paths differ by platform:

The General Settings panel lets you override these paths per platform — see General settings.

What the MCP server entry looks like

For Claude Code, the JSON block Ideafy writes into .claude/settings.json:

{
  "mcpServers": {
    "ideafy": {
      "command": "npx",
      "args": ["tsx", "<path-to-ideafy-mcp-server>/index.ts"]
    }
  }
}

The path points at the copy of mcp-server/index.ts that the Ideafy app bundles. The server reads your local SQLite database directly and calls back to the Ideafy API for pool operations. It reads one environment variable you care about:

• IDEAFY_CARD_ID — set by the app when it spawns a terminal on a card, so the agent knows which card it's working on. You generally never set this yourself.

What the hook does

The UserPromptSubmit hook injects a system reminder whenever $IDEAFY_CARD_ID is set in the shell environment. The reminder is short and prescriptive:

Ideafy Card: Before finishing, update the card:

• After planning: save_plan (moves to In Progress)
• After implementation: save_tests (moves to Human Test)
• After idea discussion: save_opinion

This is why, when you open a card's terminal from Ideafy, the agent automatically knows to call the right save tool when it's done. Without the hook, the agent would work freely but not move the board.

Verifying the install

After clicking Install Ideafy in a project, open a terminal in that project and run your agent CLI. It should list ideafy as an available MCP. If Claude Code:

claude mcp list

You should see ideafy in the list. If you ask the agent "list my cards," it should call mcp__ideafy__list_cards and return a table.

If any of that fails, see Troubleshooting.

Switching platforms later

The General Settings panel has an AI platform dropdown. Switching it updates the default paths Ideafy uses for new project installs, but existing projects keep the configuration they were installed with. If you want to re-point an existing project at a different platform, re-run the install from the project settings modal.

Per-card overrides exist too — on any card, you can pick a different aiPlatform just for that one card. Useful when you want Gemini's long-context model to read a big codebase even though you usually use Claude Code. See Choose an AI agent.

Prev: Your first project Next: Board overview Up: User guide index