Devscribe Reason

An MCP server that automatically captures the reasoning behind engineering decisions made during Claude Code sessions and commits them as structured markdown files to /docs/decisions/ in your GitHub repo.

The Problem

When developers and AI agents write code, the reasoning behind decisions — why this approach over alternatives, what tradeoffs were made, what was considered and rejected — lives only in the chat session and disappears when it closes. Devscribe Reason captures that reasoning automatically in real time.

Quick Start

One command, 30 seconds, fully configured:

GITHUB_TOKEN=ghp_your_personal_access_token npx devscribe-reason

That's it. The MCP server is now active in all your Claude Code sessions. Reasoning docs auto-commit to /docs/decisions/.

How It Works

The server exposes four MCP tools that Claude Code calls throughout a coding session automatically — no manual configuration required:

| Tool | When It's Called | What It Does | |------|-----------------|--------------| | log_intent | Start of session | Records what you're building and why | | log_decision | When a technical choice is made | Captures the decision, reasoning, and code context | | log_alternative | When an approach is rejected | Documents what was considered and why it was dropped | | finalize_reasoning_doc | When work is done | Automatically triggered when you say "we're done", "open a PR", etc. |

Setup

Option 1: NPM (Recommended)

# Install globally and configure in one step
GITHUB_TOKEN=ghp_your_personal_access_token npx devscribe-reason

The setup script will:

• Detect your Claude Code installation automatically
• Register devscribe-reason as a user-level MCP server (works in all repos)
• Auto-detect your GitHub repo from the current directory
• Done! Restart Claude Code

Option 2: Docker / Development

git clone https://github.com/YOUR_USERNAME/Devscribe-Reason.git
cd Devscribe-Reason
npm install
npm run setup

Environment Variables

Required:

• GITHUB_TOKEN — Personal Access Token with repo scope

Optional (auto-detected):

• GITHUB_REPO — GitHub repo (owner/repo), auto-detected from git remote
• GITHUB_BRANCH — Target branch (default: main)

Optional (webhook auto-finalization):

• WEBHOOK_PORT — Port for GitHub webhook listener (e.g., 3001)
• GITHUB_WEBHOOK_SECRET — GitHub webhook secret (both env vars required to activate)

Features

✅ Zero setup — Inject instructions via MCP protocol, no CLAUDE.md needed ✅ Automatic logging — Captures decisions silently throughout your session ✅ Natural language triggers — Say "we're done", "ship it", "open a PR" — anything works ✅ GitHub webhook — Auto-finalize reasoning docs when PRs are opened (optional) ✅ Auto-detect repo — Parses git remote to populate GITHUB_REPO automatically ✅ Global MCP server — Works in every repo, configured once at user level

Output

Each session produces a markdown file in /docs/decisions/ like:

docs/decisions/2026-03-06-auth-refactor-oauth.md

With structured sections: Intent, Key Decisions, Alternatives Considered, Open Questions, and Links.

GitHub Webhook (Optional)

To auto-commit reasoning docs when PRs are opened:

1. Create a GitHub App or use a Personal Access Token with webhook permissions
2. Run the server with:

   WEBHOOK_PORT=3001 GITHUB_WEBHOOK_SECRET=your_secret npm start

3. Add webhook in GitHub repo settings:
   • Payload URL: https://your-domain.com/webhook
   • Events: Pull Requests
   • Secret: your_secret

When a PR is opened, the reasoning doc is automatically committed to the PR's base branch.

Troubleshooting

"Could not find the 'claude' command"

• Ensure Claude Code CLI or VS Code/Cursor with Claude Code extension is installed
• Reinstall: npm run setup

"MCP server already exists"

• The server is already registered. To re-register: claude mcp remove --scope user devscribe-reason then run setup again

Reasoning docs not committing

• Verify GITHUB_TOKEN has repo scope
• Check that GITHUB_REPO is set correctly: echo $GITHUB_REPO
• Verify the repo exists and the token has push access

License

MIT