Skip to main content

Claude Code Setup

This guide shows you how to set up Claude Code to automatically log thoughts to AGIT.

Prerequisites​

Automatic Setup​

When you run agit init, a CLAUDE.md file is created automatically. Claude Code reads this file and follows its instructions.

Restart Required

After running agit init or agit init --update, restart your Claude Code session to load the updated AGIT configuration. The CLI will remind you:

Restart your AI assistant to activate AGIT memory.

How It Works​

  1. Claude Code reads CLAUDE.md when starting a session
  2. While working, Claude sees instructions to log thoughts
  3. Claude calls agit_log_step via MCP
  4. Thoughts are stored in .agit/index

The CLAUDE.md File​

The generated file contains instructions like:

# AGIT Integration

This project uses AGIT to capture reasoning context.

## Instructions

When working on tasks in this project:

1. Log the user's intent when they describe what they want:
   - Call `agit_log_step` with role="user", category="intent"

2. Log your reasoning when you decide on an approach:
   - Call `agit_log_step` with role="ai", category="reasoning"

3. For significant decisions, log them as well.

This creates a trace that gets linked to git commits.

Verifying It Works​

  1. Start Claude Code in your project directory
  2. Ask Claude to help with a task
  3. Check AGIT status:
agit status

Expected output:

Staging area:
  2 entries pending

Recent entries:
  [14:22:31] user/intent: Refactor authentication module
  [14:22:35] ai/reasoning: Will extract auth logic into separate service

Customizing Instructions​

You can edit CLAUDE.md to customize logging behavior:

Add Custom Categories​

## Logging Categories

- `intent`: User's goal
- `reasoning`: Your approach
- `decision`: Technical decisions
- `alternative`: Considered but rejected options

Control Logging Frequency​

## When to Log

- Always log the initial user request
- Log when choosing between approaches
- Log significant technical decisions
- Don't log minor implementation details

Best Practices​

Clear Task Descriptions​

Give Claude clear context:

"I want to add rate limiting to the API endpoints.
The goal is to prevent abuse while not affecting legitimate users.
We're using Express.js."

Encourage Explanation​

Ask Claude to explain before acting:

"Before implementing, explain your approach and any trade-offs."

Regular Commits​

Commit frequently to keep reasoning traces focused:

# After completing a logical unit of work
git add .
agit commit -m "Add rate limiting middleware"

Troubleshooting​

Nothing Being Logged​

  1. Verify CLAUDE.md exists in project root
  2. Check AGIT is initialized: ls .agit
  3. Restart Claude Code session - this is required after init or update
  4. If you updated AGIT, run agit init --update then restart again

MCP Not Connecting​

  1. Ensure agit is in your PATH
  2. Try running agit server manually
  3. Check for error messages in Claude Code

Logs Missing Context​

Edit CLAUDE.md to add more specific instructions about what to log.

Next Steps​