Bundled Claude Code hooks

Hooks are shell commands that run at specific points in the agent's lifecycle. Ideafy installs a UserPromptSubmit hook — it runs every time you submit a message to the agent — that injects card context into the conversation without you having to mention it.

What the hook does

On every prompt submit, the hook checks whether the $IDEAFY_CARD_ID environment variable is set. If it is, it emits a <system-reminder> block the agent reads before responding:

Ideafy Card: <id>
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

That tiny reminder is what keeps the agent anchored to the card. Without it, the agent has no way to know which card you're working on when you say "move this to testing." With it, the agent always has the card ID in scope and the three workflow tools at the top of its mind.

When is IDEAFY_CARD_ID set?

Ideafy sets the env var only when it spawns a terminal or background process on a specific card — autonomous, quick-fix, evaluate, interactive terminal. Outside those contexts (you running Claude Code directly from your shell, not from Ideafy), the variable is unset and the hook is a no-op. So it doesn't pollute general agent use.

The second hook (repo-only)

In the Ideafy repo itself, there's a second UserPromptSubmit hook that injects a solo/cloud repository classification reminder. That one is specific to Ideafy development — it tells the agent which of the two repos (ideafy public vs. ideafy-cloud private) the current directory belongs to and what rules apply. You won't see it in your own projects; it's part of the Ideafy codebase, not what the install button writes.

Installing and removing

POST /api/projects/[id]/hook installs the hook into the project's .claude/settings.json. DELETE removes it. The project settings modal exposes both operations. The install is idempotent — you can click it multiple times without duplicating the hook entry.

If you want to verify, open .claude/settings.json in the project root and look for:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          { "type": "command", "command": "if [ -n \"$IDEAFY_CARD_ID\" ]; ..." }
        ]
      }
    ]
  }
}

Writing your own hooks

Ideafy doesn't get in the way of you adding more hooks. The hook array is part of your project's config, not Ideafy's — you can append additional hooks for PreToolUse, PostToolUse, Stop, or other events. Ideafy only manages the single UserPromptSubmit entry it installs. Your additions are preserved across install/uninstall.

See the Claude Code documentation for the full list of hook events and their capabilities.

When to turn the hook off

You almost never need to. But if you want to:

• Click Uninstall Ideafy Hooks in the project settings modal, or
• Edit .claude/settings.json by hand and remove the UserPromptSubmit entry Ideafy added

Card terminal sessions still work without the hook — you just lose the automatic reminder, so the agent is more likely to forget which card it was on. Use the other two workflow anchors instead (mention the card ID directly, or stay in the card modal chat panel which already has the card context baked in).

Prev: Bundled Claude Code skills Next: MCP tools reference Up: User guide index