200notes Claude Code Integration

NEW in v0.2.0: 🎉 Claude Code Hooks - Fully automatic task tracking! No more manual PROJECT.md updates.

Seamless integration between Claude Code and 200notes project management. Automatically track tasks, update progress, and maintain project context during your AI-assisted development sessions.

✨ Features

🆕 v0.2.0 - Claude Code Hooks (NEW!)

• 🔄 Fully Automatic Task Tracking: Zero manual updates - tasks update automatically when you code
• 🎯 Smart File-to-Task Mapping: PaymentController.php → automatically finds "payment", "stripe" tasks
• ✅ Commit Pattern Recognition: git commit -m "closes #123" → Task #123 automatically marked done
• 📝 Auto CLAUDE.md Updates: Project context refreshed automatically after code changes

🚀 Core Features

• 🤖 Claude Code Integration: Deep integration with Claude Code workflow
• 📋 Intelligent Task Management: Advanced CLI for creating, updating, and tracking tasks
• ⚡ Real-time Team Sync: Keep your team in sync with automatic progress updates
• 🔍 Keyword-Based Task Mapping: Find and update tasks using file keywords

🚀 Quick Start

Installation

Option 1: NPM (Recommended)

npm install -g @200notes/claude-code

Option 2: Quick Install Script

# One-line installer
curl -fsSL https://raw.githubusercontent.com/robertspektor/200notes-claude-code-cli/main/install.sh | bash

Option 3: Manual Git Installation

# Clone and build the package
git clone https://github.com/robertspektor/200notes-claude-code-cli.git
cd 200notes-claude-code-cli
npm install
npm run build

# Install globally
npm link

Option 4: Direct Download

# Download and install latest release
curl -L https://github.com/robertspektor/200notes-claude-code-cli/archive/main.zip -o claude-code.zip
unzip claude-code.zip
cd 200notes-claude-code-cli-main
npm install && npm run build && npm link

Option 5: Using npx

npx @200notes/claude-code init "My Project"

Setup

1. Configure your API credentials (get them from your 200notes dashboard):

200notes auth login

2. Initialize your project:

cd your-project
200notes init "My Awesome Project"

3. Set up Claude Code Hooks (for automatic tracking):

# Copy hooks to your project
cp -r "$(npm root -g)/@200notes/claude-code/hooks" ./hooks/
chmod +x hooks/*.sh

# Configure Claude Code (see HOOK_SETUP.md for details)

4. Start Claude Code - tasks will now be automatically tracked!

Example Workflow

# Check current project status
200notes status

# Create a new task
200notes task create "Implement user authentication" --priority high --tags auth,backend

# Start working on a task
200notes task start "authentication"

# Mark a task as completed
200notes task done 123

# NEW in v0.2.0: Update tasks by file keywords
200notes task update dummy --file-keywords "auth,payment" --status in_progress

# Auto-update CLAUDE.md with current project context
200notes sync --update-claude-md

📖 How It Works

Automatic Task Updates

When you make changes with Claude Code, the integration:

1. Detects file changes through Claude Code hooks
2. Maps changes to tasks using intelligent keyword matching
3. Updates task status automatically (todo → in_progress → done)
4. Syncs with your team in real-time

Smart Task Mapping

The integration uses advanced algorithms to understand which tasks relate to your code changes:

• File path analysis: src/auth/login.ts → tasks tagged with "auth", "login"
• Content analysis: Function names, classes, imports
• Keyword extraction: Smart parsing of code comments and documentation
• Pattern recognition: Framework-specific patterns (React, Laravel, etc.)

CLAUDE.md Integration

Your project automatically gets a CLAUDE.md file that provides Claude with:

• Current task status and priorities
• Project context and recent changes
• Suggested next steps
• Team member assignments

🛠️ CLI Reference

Project Management

# Initialize project
200notes init [project-name]

# Show project status
200notes status
200notes status --all  # Include completed tasks
200notes status --filter todo  # Filter by status

# Sync with 200notes
200notes sync

Task Management

# Create tasks
200notes task create "Task title"
200notes task create "Fix bug" --priority high --tags bug,urgent

# Update tasks
200notes task update 123 --status in_progress
200notes task update 123 --priority high --description "New description"

# Quick status changes
200notes task start 123  # Mark as in_progress
200notes task done 123   # Mark as completed

# Delete tasks
200notes task delete 123

Authentication

# Login with API credentials
200notes auth login

# Check authentication status
200notes auth status

# Logout
200notes auth logout

⚙️ Configuration

Global Configuration

Stored in ~/.config/200notes/config.json:

{
  "apiKey": "your-api-key",
  "apiSecret": "your-api-secret",
  "baseUrl": "https://200notes.com"
}

Project Configuration

Stored in .200notes.json in your project root:

{
  "projectId": "project-uuid",
  "name": "Project Name",
  "lastSync": "2024-01-15T10:30:00.000Z",
  "taskMappings": {
    "src/auth/": [123, 124, 125],
    "src/api/": [126, 127]
  },
  "settings": {
    "autoStartTasks": true,
    "autoCompleteTasks": false,
    "trackFileChanges": true,
    "excludePatterns": ["node_modules/**", "dist/**"]
  }
}

🔧 Claude Code Hooks

NEW in v0.2.0: Fully automatic task tracking through Claude Code integration!

👉 See HOOK_SETUP.md for complete installation guide

The integration installs Claude Code hooks that automatically:

PostToolUse Hook

Runs after successful tool execution:

• Edit/Write/MultiEdit: Updates related tasks to "in_progress"
• Bash commands: Detects completion patterns in commits
• File changes: Maps modifications to relevant tasks

Session Tracking

Tracks your development session:

• Files modified
• Tasks updated
• Time spent on different areas
• Progress summaries

🎯 Advanced Usage

Custom Task Mapping

You can create custom mappings for better task detection:

{
  "keywords": {
    "stripe": [123, 124],
    "payment": [123, 124, 125],
    "webhook": [126],
    "authentication": [127, 128]
  }
}

Team Collaboration

When working in teams:

• Conflict detection: Warns when multiple people work on the same task
• Status sync: Real-time updates across team members
• Assignment tracking: See who's working on what

Integration with Git

The hooks can parse git commit messages:

git commit -m "closes task #123: Implement user authentication"
# Automatically marks task #123 as completed

🔌 API Reference

Programmatic Usage

import { NotesApiClient, ConfigManager, TaskMappingEngine } from '@200notes/claude-code';

// Get API client
const config = await ConfigManager.getApiConfig();
const client = new NotesApiClient(config);

// Get project tasks
const tasks = await client.getTasks(projectId);

// Find related tasks
const keywords = TaskMappingEngine.extractKeywordsFromPath('src/auth/login.ts');
const relatedTasks = TaskMappingEngine.findMatchingTasks(tasks, keywords);

// Update task status
await client.updateTaskStatus(taskId, 'in_progress');

🌟 Examples

Laravel Project

# Initialize Laravel project
200notes init "E-commerce API"

# Create tasks for common Laravel features
200notes task create "Setup authentication" --tags auth,laravel
200notes task create "Create product model" --tags model,products
200notes task create "Implement payment gateway" --tags stripe,payments

# Work on authentication - files in app/Http/Controllers/Auth/ 
# automatically update the auth task to "in_progress"

React Project

# Initialize React project  
200notes init "Dashboard App"

# Create component-based tasks
200notes task create "User profile component" --tags react,components
200notes task create "API integration" --tags api,axios
200notes task create "State management" --tags redux,state

# Changes in src/components/UserProfile.tsx 
# automatically link to the profile component task

🔒 Security

• API credentials are stored securely in your local config
• No code content is sent to 200notes servers
• Only metadata (file paths, task mappings) are synchronized
• Local processing for keyword extraction and task mapping

📋 Changelog

v0.2.0 (Latest) - Claude Code Hooks

• ✅ NEW: Fully automatic task tracking via Claude Code hooks
• ✅ NEW: --file-keywords parameter for task updates by file patterns
• ✅ NEW: --update-claude-md for automatic CLAUDE.md generation
• ✅ NEW: Commit pattern recognition (closes #123 → task done)
• ✅ NEW: Smart file-to-task mapping algorithms
• ✅ NEW: Complete hook setup documentation
• 🔧 Improved: CLI commands and error handling

v0.1.0 - Initial Release

• ✅ Basic CLI for task management
• ✅ 200notes API integration
• ✅ Project initialization and authentication
• ✅ Manual task creation and updates

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 License

MIT License - see the LICENSE file for details.

🔧 Troubleshooting

Installation Issues

"Package not found" error

npm error 404 Not Found - GET https://registry.npmjs.org/@200notes%2fclaude-code

Solution: Make sure you're using the correct package name: @200notes/claude-code. If the error persists, try the Git installation method instead.

Permission errors during global install

# Use sudo (macOS/Linux)
sudo npm link

# Or configure npm for global installs without sudo
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

"command not found: 200notes"

Solution:

1. Ensure the package was linked successfully: npm list -g @200notes/claude-code
2. Check your PATH includes npm global bin: npm config get prefix
3. Restart your terminal

TypeScript compilation errors

# Ensure you have the right Node.js version
node --version  # Should be 18.0.0 or higher

# Clean install
rm -rf node_modules package-lock.json
npm install
npm run build

Runtime Issues

"Authentication failed" errors

1. Verify your API credentials in 200notes dashboard
2. Check config file: ~/.config/200notes/config.json
3. Re-authenticate: 200notes auth logout && 200notes auth login

"Project not found" errors

1. Ensure you've run 200notes init in your project directory
2. Check for .200notes.json file in project root
3. Verify project exists in 200notes dashboard

Tasks not updating automatically

1. Check that Claude Code hooks are installed: ls -la hooks/
2. Verify hook permissions: chmod +x hooks/*.sh
3. Check exclude patterns in .200notes.json

Development Setup

For contributors and development:

# Clone the repository
git clone https://github.com/robertspektor/200notes-claude-code-cli.git
cd 200notes-claude-code-cli

# Install dependencies
npm install

# Build in watch mode
npm run dev

# Run tests
npm test

# Link for local development
npm link

# Test CLI locally
200notes --version

🆘 Support

• Documentation: docs.200notes.com
• Issues: GitHub Issues
• Discord: Join our community
• Email: [email protected]

Made with ❤️ by the 200notes team