GitCraft AI Studio

🚀 AI-driven Git management platform powered by Claude and modern web technologies - Build, manage, and deploy with AI assistance.

🔧 Latest Update: Comprehensive help system with Japanese/English documentation and enhanced UI!

📑 Table of Contents

✨ Features
🛠️ Tech Stack
📋 Prerequisites
🚀 Quick Start
📖 Documentation
🔧 System Management
💬 Claude Integration
📊 Database Management
📖 Usage Guide
🏗️ Project Structure
🔌 API Reference
💻 Development
🐛 Troubleshooting
🤝 Contributing
📄 License
📸 Screenshots

📸 Screenshots

🖥️ User Interface

Main application interfaces with light theme design

Dashboard Overview

Main dashboard with system status, Claude AI progress, and task overview

Repository Management

Repository list with status indicators, stats, and quick actions

Repository Details

Detailed repository view with Git operations and file management

Task Management

Task workflow with status filtering, progress tracking, and priority management

Claude Code Integration

Real-time command tracking with repository selection and session monitoring

Claude Code CLI

Claude CLI interface for AI-powered development

AI Assistant Settings

AI configuration and Claude integration settings

🏗️ Architecture & Workflow

Technical architecture and integration flows

Claude Integration Architecture

Complete architecture diagram showing how Claude CLI integrates with GitCraft AI Studio

Claude Workflow

Step-by-step workflow for Claude integration: Regular work → Recap → Commit

Command Tracking Flow

Real-time command tracking flow from Claude CLI to web interface

Auto-Commit and Push

Automatic Git operations triggered by Claude commands

Claude CLI Tools

Available Claude CLI tools and their integration with GitCraft

Troubleshooting Flow

Common troubleshooting steps and solutions for Claude integration

✨ Features

🎯 Core Features

🤖 AI-Powered Development: Automated code generation, review, and refactoring with Claude AI (4 models)
📋 Smart Task Management: Complete workflow (TODO → IN_PROGRESS → IN_REVIEW → APPROVED → COMPLETED)
🗂️ Repository Management: GitHub integration with local repository support and path editing
🔐 Secure Authentication: Email/password with NextAuth.js and password reset
📊 Tech Stack Templates: Create and share technology stack configurations
🔄 Real-time Collaboration: WebSocket-powered editing with cursor tracking
🌿 Smart Git Operations: Automatic branch creation, merging, and push
📖 Comprehensive Help System: Built-in documentation with search and multi-language support
🔔 Notifications (Under Development): Desktop and sound notifications for task updates

🌐 Internationalization & User Experience

🎌 Multi-language Support: Complete Japanese & English interface
🔍 Advanced Help System: Searchable documentation with 10 help sections including:
- Getting Started guide with step-by-step onboarding
- Installation & Setup guide for Claude Code and GitCraft
- Repository Management with private repository access
- Troubleshooting with 6 common issues and solutions
- Task Management and AI integration guides
📱 Responsive Design: Modern UI with mobile-first approach
🎨 Theme Support: Light/Dark/System theme switching
🔧 Settings Management: Comprehensive configuration system

🤖 Claude Integration Features

📝 Command Tracking: Real-time monitoring of Claude CLI commands
💾 Conversation Auto-save: Automatic saving with AI-generated summaries
🔍 Session Browser: Search and browse past Claude sessions with statistics
🔄 Auto-commit/Push: Automatic Git operations triggered by ANY command (3-second delay)
📊 Session Analytics: Track Claude usage patterns and productivity
🎯 Task Creation: Convert Claude sessions directly into tasks
🔧 Hook System: Custom tool execution hooks for automation
🚀 Include Untracked: Automatically commits ALL files including untracked ones
📝 Simplified Workflow: Use "recap" for summaries and "commit" for execution

🧠 AI Capabilities

Code Generation: Context-aware implementation from descriptions
Code Review: AI-powered reviews with actionable suggestions
Smart Commits: Auto-generate conventional commit messages
Code Refactoring: Optimize for performance and readability
Code Explanation: Interactive explanations with complexity control

🛠️ Tech Stack

Frontend

Framework: Next.js 15.2+, React 19.1, TypeScript 5.8
UI Components: shadcn/ui, Radix UI, Lucide Icons
Styling: Tailwind CSS 4.1, CSS Modules
State Management: React Context, tRPC Query
Real-time: WebSocket client, Server-Sent Events
Internationalization: next-intl for multi-language support
Code Editor: Monaco Editor with syntax highlighting

Backend

API: tRPC 11.1, Express middleware
Database: PostgreSQL 16, Prisma ORM 5.22
Authentication: NextAuth.js, bcrypt
Real-time: WebSocket server, Chokidar for file watching
Process Management: PM2 for persistent services

AI & Integrations

AI: Claude CLI (development) / Anthropic API (production)
Git: simple-git, isomorphic-git
Build Tools: Turborepo, pnpm workspaces
Development: TypeScript 5.8, ESLint, Prettier

📋 Prerequisites

Required

Node.js 22.17.0+ (use nvm recommended)
pnpm 10.13.0+ (npm install -g pnpm)
Git 2.34+
PostgreSQL 16+

Optional

Claude CLI (for development mode)
Anthropic API Key (for production)

PM2 (for persistent services and Claude tracking)

# Install PM2 globally
sudo npm install -g pm2
# Or without sudo using npx
npx pm2

GitHub Personal Access Token (for private repos)

🚀 Quick Start

1️⃣ Clone Repository

git clone https://github.com/cruzy-jpn/gitcraft-ai-studio.git
cd GitCraft-AI-Studio-develop

2️⃣ Install pnpm (if not already installed)

# Option 1: Using npm with sudo
sudo npm install -g pnpm

# Option 2: Using standalone installer (no sudo required)
curl -fsSL https://get.pnpm.io/install.sh | sh -

# Option 3: Using Corepack (Node.js 16.13+)
corepack enable
corepack prepare pnpm@latest --activate

3️⃣ One-Command Setup

# Initialize everything automatically
./init.sh

This will:

✅ Install all dependencies
✅ Set up PostgreSQL database
✅ Create environment files with symlinks
✅ Initialize database schema
✅ Initialize empty database (no default users)
✅ Set up required directories

Note: The project now uses a single .env file in the root directory. The init script will create symlinks from apps/api/.env and apps/web/.env.local to the root .env file.

4️⃣ Environment Configuration

Important: All environment variables are managed in the root .env file. The application uses these variables for paths:

# Project root directory (defaults to current working directory)
GITCRAFT_PROJECT_ROOT=/path/to/your/project

# Log directory for Claude commands (defaults to project root)
GITCRAFT_LOG_DIR=/path/to/log/directory

# Session directory for Claude sessions (defaults to project root)
GITCRAFT_SESSION_DIR=/path/to/session/directory

Note: Some shell scripts (claude-wrapper.sh) may need manual configuration. Use claude-wrapper-template.sh as a starting point.

5️⃣ Start All Services

# Recommended: Start everything with one command
./start-all.sh

# This starts:
# - API server (port 4000)
# - Web server (port 3000)
# - Claude command tracking (integrated in API)
# - Creates necessary log files

6️⃣ Access the Application

Open your browser and navigate to:

🌐 Main App: http://localhost:3000
📖 Help System: http://localhost:3000/help
🤖 Claude Integration: http://localhost:3000/claude-integration
🗄️ Database GUI: npx prisma studio (from apps/api)

7️⃣ Verify Installation

# Check system health
./check-system.sh

📖 Documentation

📚 Built-in Help System

GitCraft AI Studio includes a comprehensive help system accessible at /help with:

🔍 Search Functionality

Real-time search across all documentation
Instant filtering of help topics
Keyboard shortcuts for quick navigation

📖 Complete Documentation Sections

Getting Started - New user onboarding with 4-step guide
Installation & Setup - Claude Code and GitCraft installation
Repository Management - GitHub integration and private repository access
Task Management - AI-powered task workflow (coming soon)
Claude AI Integration - AI development features (coming soon)
Git Operations - Version control and collaboration (coming soon)
Troubleshooting - 6 common issues with solutions
Settings & Configuration - Workspace customization (coming soon)
Collaboration - Real-time development features (coming soon)
API Reference - Developer documentation (coming soon)

🌐 Multi-language Support

Complete English documentation
Full Japanese translations
Language switching via settings
Localized examples and code snippets

🛠️ Interactive Features

Copy-to-clipboard code blocks
Expandable troubleshooting sections with severity indicators
External links to official documentation
Quick navigation between related topics

📝 Key Help Sections

Getting Started

System overview and feature introduction
4-step onboarding process with visual indicators
Next steps recommendations

Installation & Setup

Prerequisites with version requirements
Claude Code CLI installation guide
GitCraft setup with environment configuration
Database setup instructions for multiple platforms

Repository Management

Comprehensive guide to adding repositories
Private repository access with GitHub tokens
Repository management operations
Best practices and security considerations

Troubleshooting

6 common issues with step-by-step solutions:
- Repository has no initial commit
- Repository path mismatch
- Claude AI authentication failed
- Database connection failed
- Git push operation failed
- Task execution failed
Quick links for common problems
Additional resources and external documentation

📦 PostgreSQL Setup (Manual)

If you need to set up PostgreSQL manually:

# Ubuntu/Debian
sudo apt update
sudo apt install -y postgresql postgresql-contrib

# macOS
brew install postgresql
brew services start postgresql

# Create database and user
sudo -u postgres psql << EOF
CREATE USER gitcraft WITH PASSWORD 'gitcraft_dev_2025';
CREATE DATABASE gitcraft_studio OWNER gitcraft;
GRANT ALL PRIVILEGES ON DATABASE gitcraft_studio TO gitcraft;
ALTER USER gitcraft CREATEDB;
EOF

For other methods (Docker, cloud services), see PostgreSQL Setup Guide.

🔧 System Management

Start/Stop Services

# Start all services
./start-all.sh

# Stop all services
./stop-all.sh

# Check system health
./check-system.sh

Service Management Details

The start-all.sh script manages:

API Server: Backend services on port 4000
Web Server: Frontend on port 3000
Claude Tracker: PM2 process for command tracking
Health Monitoring: Continuous system checks

Logs and Monitoring

# View API logs
tail -f apps/api/dev.log

# View Web logs
tail -f apps/web/dev.log

# View Claude tracker logs
pm2 logs claude-track

# View all PM2 processes
pm2 status

Usage Guide

Task Workflow

Create Task: Define what needs to be built with title and description
AI Implementation: Claude generates code based on task description and tech stack
Source Review: Review generated code and request modifications if needed
Approval: Approve the implementation when satisfied
Merge to Main: Merge approved code to main branch with automatic commit and push

Repository Management

Add Repository: Click "Add Repository" and provide the clone URL
Directory Name: Automatically extracted from URL, customizable before cloning
Clone Path: Repositories are cloned to /GitCraft-AI-Studio-develop/{repository-name}

GitHub Integration: Use personal access tokens for private repositories:

https://<TOKEN>@github.com/username/repository.git

⚠️ Important: We strongly recommend using private repositories on GitHub to protect your code and intellectual property.

📌 Note for Empty GitHub Repositories: If you've created a new repository on GitHub without any commits:

# First, initialize the repository locally
echo "# your-repository-name" >> README.md
git init
git add README.md
git commit -m "first commit"
git branch -M main
git remote add origin https://github.com/username/your-repository-name.git
git push -u origin main

# Then add it to GitCraft AI Studio

Branch Management: Automatic branch creation for each task
Merge Operations: One-click merge to main with automatic push
Path Management: Update repository paths in settings if location changes

Real-time Collaboration

Collaborative Editing: Multiple users can edit files simultaneously
Cursor Tracking: See other users' cursor positions in real-time
Typing Indicators: Visual indicators when other users are typing
Room Management: Repository-based collaboration rooms

🏗️ Project Structure

GitCraft-AI-Studio-develop/
├── apps/
│   ├── web/                      # Next.js frontend application
│   │   ├── app/                  # App router pages
│   │   │   └── [locale]/         # Internationalized routes
│   │   │       ├── help/         # Help system pages
│   │   │       │   ├── page.tsx  # Main help landing page
│   │   │       │   ├── getting-started/
│   │   │       │   ├── installation/
│   │   │       │   ├── repositories/
│   │   │       │   └── troubleshooting/
│   │   │       └── settings/     # Settings pages
│   │   ├── components/           # React components
│   │   │   ├── claude/          # Claude integration components
│   │   │   ├── ui/              # UI components (shadcn)
│   │   │   └── layout/          # Layout components
│   │   ├── lib/                  # Utilities and hooks
│   │   │   └── i18n/            # Internationalization
│   │   │       └── translations/ # Translation files
│   │   │           ├── en.json   # English translations
│   │   │           └── ja.json   # Japanese translations
│   │   └── .env.local            # Web app environment
│   └── api/                      # Backend API server
│       ├── src/
│       │   ├── api/              # tRPC routers
│       │   │   └── routers/      # API endpoints
│       │   ├── services/         # Business logic
│       │   └── db/               # Database client
│       ├── prisma/               # Database schema
│       └── scripts/              # Utility scripts
├── packages/
│   └── shared/                   # Shared types and schemas
├── .claude-sessions/             # Claude conversation storage
├── .claude-instructions          # Claude workflow configuration
├── docs/                         # Documentation
├── scripts/                      # System management scripts
│   ├── init.sh                   # Project initialization
│   ├── cleanup.sh                # Cleanup and reset
│   ├── start-all.sh              # Start all services
│   ├── stop-all.sh               # Stop all services
│   └── check-system.sh           # System health check
└── git-repositories/             # Cloned repositories

🔌 API Reference

Core API Endpoints (tRPC)

Authentication

auth.login - User login with email/password
auth.register - Create new user account
auth.logout - End user session
auth.getSession - Get current user session
auth.updateProfile - Update user profile

Tasks

tasks.list - List all tasks with filtering
tasks.create - Create new task
tasks.update - Update task status/details
tasks.delete - Delete task
tasks.getById - Get single task details
tasks.updateStatus - Change task workflow status

Repositories

repositories.list - List user repositories
repositories.create - Add new repository
repositories.clone - Clone remote repository
repositories.delete - Remove repository
repositories.updatePath - Update repository local path
repositories.getBranches - List repository branches
repositories.createBranch - Create new branch
repositories.merge - Merge branch to main

Claude Sessions

claudeSessions.list - List all Claude sessions
claudeSessions.search - Search sessions by content
claudeSessions.getById - Get session details
claudeSessions.getStatistics - Usage analytics
claudeSessions.createTaskFromSession - Convert to task

Tech Stacks

techStacks.list - List available tech stacks
techStacks.create - Create custom stack
techStacks.update - Modify tech stack
techStacks.delete - Remove tech stack

WebSocket Events

Command Tracking

command:new - New Claude command executed
command:update - Command status updated
session:start - Claude session started
session:end - Claude session ended

Collaboration

room:join - User joined editing room
room:leave - User left editing room
cursor:update - Cursor position changed
content:update - File content changed

Utility Scripts

Database Management

# List all users
cd apps/api && npx tsx scripts/list-users.ts

# List repositories
cd apps/api && npx tsx scripts/list-repositories.ts

# Check completed tasks
cd apps/api && npx tsx scripts/check-completed-tasks.ts

# Verify auth token
cd apps/api && npx tsx scripts/verify-token.ts

Claude Integration

# Track commands manually
node track-claude-command.js <tool> <action> [params]

# Manage Claude sessions
node claude-conversation-manager.js

# Save current web session
node save-current-web-session.js

🚀 Initialization and Cleanup

Initial Setup (First Time Only)

The init.sh script handles all initialization automatically:

./init.sh

What it does:

✅ Installs all dependencies with pnpm
✅ Creates environment files from templates
✅ Sets up PostgreSQL database configuration
✅ Runs database migrations
✅ Creates default users
✅ Creates necessary directories (git-repositories, logs)
✅ Validates the setup
✅ Creates .claude-commands.log for Claude integration tracking

🧹 Cleanup Procedures

The cleanup.sh script provides various cleanup options:

Basic Cleanup (Keep Database)

./cleanup.sh

🗑️ Removes cloned git repositories
🗑️ Clears temporary files
✅ Keeps database and user data intact

Database Reset

./cleanup.sh --reset-db

🗑️ Removes all database data
🔄 Recreates database schema
🗑️ Clears all git repositories
⚠️ All users and tasks will be deleted

Complete Cleanup

./cleanup.sh --all --reset-db

🗑️ Everything from database reset
🗑️ Removes node_modules
🗑️ Clears build artifacts (.next, dist)
🗑️ Removes log files
🔄 Returns project to fresh state
⚠️ Does not remove PostgreSQL installation

Skip Confirmation

./cleanup.sh -y --reset-db

⚡ Runs cleanup without confirmation prompts
🚀 Useful for CI/CD pipelines

🔄 Re-initialization After Cleanup

After running cleanup, re-initialize the project:

# After basic cleanup
pnpm dev  # Just start the servers

# After database reset
./init.sh  # Full re-initialization

# After complete cleanup
./init.sh  # Full re-initialization required

📊 Database Management

View Database

cd apps/api
npx prisma studio  # Opens at http://localhost:5555

Manual Database Operations

# Reset database manually
cd apps/api
npx prisma migrate reset --force

# Run specific migration
npx prisma migrate dev

# Generate Prisma client
npx prisma generate

🔄 Database Rebuild Procedures

Once a database has been created and used, you may need to rebuild it completely. Here are the procedures:

Option 1: Complete Database Reset (Recommended)

# Use the cleanup script with database reset
./cleanup.sh --reset-db

# Then re-initialize
./init.sh

This will:

Drop all tables and data
Recreate the database schema
Create a fresh database with initial users
Clear all git repositories

Option 2: Manual Database Rebuild

# 1. Stop all services
./stop-all.sh

# 2. Access PostgreSQL
sudo -u postgres psql

# 3. Drop and recreate database (in psql)
DROP DATABASE IF EXISTS gitcraft_studio;
CREATE DATABASE gitcraft_studio OWNER gitcraft;
GRANT ALL PRIVILEGES ON DATABASE gitcraft_studio TO gitcraft;
\q

# 4. Run migrations
cd apps/api
npx prisma migrate deploy
npx prisma generate

# 5. Create initial users (optional)
cd apps/api
npx tsx scripts/init-db.ts

# 6. Restart services
cd ../..
./start-all.sh

Option 3: Preserve User Data, Reset Everything Else

# 1. Export user data
cd apps/api
npx tsx scripts/export-users.ts > users-backup.json

# 2. Reset database
cd ..
./cleanup.sh --reset-db

# 3. Re-initialize
./init.sh

# 4. Import user data
cd apps/api
npx tsx scripts/import-users.ts < users-backup.json

Option 4: Reset Specific Tables Only

cd apps/api

# Reset only tasks and related data
npx prisma db execute --file scripts/reset-tasks.sql

# Reset only repositories
npx prisma db execute --file scripts/reset-repositories.sql

# Reset only Claude sessions
npx prisma db execute --file scripts/reset-claude-sessions.sql

🗄️ Database Backup & Restore

Create Backup

# Full database backup
pg_dump -U gitcraft -h localhost gitcraft_studio > backup_$(date +%Y%m%d_%H%M%S).sql

# Compressed backup
pg_dump -U gitcraft -h localhost gitcraft_studio | gzip > backup_$(date +%Y%m%d_%H%M%S).sql.gz

Restore from Backup

# From regular backup
psql -U gitcraft -h localhost gitcraft_studio < backup_20250127_120000.sql

# From compressed backup
gunzip -c backup_20250127_120000.sql.gz | psql -U gitcraft -h localhost gitcraft_studio

⚠️ Important Notes

Data Loss Warning: Database rebuild will delete ALL data including:
- User accounts
- Tasks and task history
- Repository configurations
- Claude sessions
- Tech stack templates
Git Repositories: Physical git repositories in git-repositories/ are NOT affected by database reset but their database records will be lost
Environment Variables: Your .env configuration will be preserved
Recommended Approach: Always use ./cleanup.sh --reset-db followed by ./init.sh for cleanest results

💬 Claude Integration

🎯 Complete GitCraft AI Studio + Claude Integration Workflow

Follow this step-by-step guide to integrate a new repository with Claude:

Step 1: Create GitHub Repository

If you haven't created a repository on GitHub yet:

Go to GitHub and create a new repository
Do NOT initialize with README, .gitignore, or license
Copy the repository URL

Step 2: Initialize Empty Repository (if needed)

If your GitHub repository has no commits:

# Navigate to where you want to create the repository
cd ~/projects  # or your preferred directory

# Create and initialize the repository
mkdir your-repository-name
cd your-repository-name
echo "# your-repository-name" >> README.md
git init
git add README.md
git commit -m "first commit"
git branch -M main
git remote add origin https://github.com/username/your-repository-name.git
git push -u origin main

Step 3: Register Repository in GitCraft AI Studio

Open GitCraft AI Studio: http://localhost:3000
Navigate to /repositories
Click "Clone Repository" button
Fill in the form:
- Repository URL: https://github.com/username/your-repository-name.git
- Name: Your repository display name
- Description: Brief description
- Directory Name: Auto-filled from URL (customizable)
- Access Token: Required for private repositories
Click "Clone" to register

Step 4: Setup Git Configuration

Go to the repository edit page: /repositories/[id]/edit
In "Git Troubleshooting" section, click "Setup Git"
This will:
- Initialize Git repository (if needed)
- Create initial commit (if needed)
- Configure remote settings
- Update branch information

Step 5: Configure Claude Integration

Navigate to /claude-integration
In "Target Repository Selection":
- Select your repository from the dropdown
- Click "Confirm Selection"
This will:
- Set the repository as Claude integration target
- Create .claude/commands/instructions.md file automatically
- Configure auto-commit and task creation

Step 6: Start Claude CLI Session

# Navigate to your repository directory
cd /path/to/GitCraft-AI-Studio/git-repositories/your-repository-name

# Start Claude CLI
claude

# Load GitCraft instructions
/instruction

This will:

Load custom GitCraft commands (recap, commit)
Configure language settings (Japanese responses if configured)
Enable command tracking and auto-commit features

Step 7: Work with Claude

Now you can work normally with Claude. All commands will be:

Tracked in real-time
Auto-committed after 3 seconds
Auto-pushed to GitHub (if authenticated)
Converted to tasks automatically

🚀 Quick Setup

# One-time setup for conversation auto-save
./setup-claude-conversation-autosave.sh
source ~/.bashrc

# Start Claude with auto-save and tracking
gc  # or gitcraft-claude

📝 Features Overview

Conversation Auto-save

🚀 Automatic Recording: All Claude CLI conversations saved automatically
📊 AI Summaries: Auto-generated summaries at session end
💾 Dual Storage: Local files + GitCraft database
🔍 Search & Browse: Find past sessions with search functionality
📈 Usage Analytics: Track productivity patterns
🌐 Web UI: View sessions at /claude-integration

Command Tracking

📝 Real-time Monitoring: Track all Claude tool usage
🔄 Auto-commit: Automatic Git operations triggered by ALL commands
🎯 Task Creation: Convert sessions to tasks instantly
📊 Session Browser: Search and analyze past sessions
🔧 Hook System: Custom automation with tool hooks
⚡ Fast Response: 5-second (default) and can set by user delay for command batching
📦 Smart Commits: Includes untracked files automatically

🗂️ Session Management

Commands

gc-sessions       # List all sessions
gc-latest         # Show latest session summary
gc-show <ID>      # Show specific session details
gc-search "query" # Search sessions
gc-stats          # Show statistics

Session Storage Structure

.claude-sessions/2024-01-20T10-30-00-000Z-a1b2c3d4/
├── metadata.json         # Session metadata
├── conversation.log      # Full conversation log
├── commands.json         # Executed commands
└── summary.json          # AI-generated summary

🔄 Auto-Commit Feature (Enhanced)

How It Works

Start Session: Click "Start Tracking" in Claude Integration page
Select Repository: Choose from dropdown or use current
Work with Claude: ALL commands trigger auto-commit (not just file changes)
Auto Task Creation: Task created after 3 seconds of ANY command
Auto Operations:
- ✅ Creates task with comprehensive command history
- ✅ Commits ALL files including untracked with git add .
- ✅ Pushes to GitHub (if authenticated)
- ✅ Marks task as COMPLETED
- ✅ 30-second minimum between auto-commits (prevents spam)

GitHub Authentication

Option 1: Personal Access Token (Recommended)

# Create token at: https://github.com/settings/tokens/new
# Scopes: repo (full control)

# Configure Git
git config --global credential.helper store
git push origin main
# Username: your-github-username
# Password: your-personal-access-token

Option 2: SSH Key

ssh-keygen -t ed25519 -C "your-email@example.com"
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519
# Add public key to GitHub settings

🛠️ Advanced Configuration

Environment Setup

# apps/api/.env
ANTHROPIC_API_KEY="claude"        # For Claude CLI
# OR
ANTHROPIC_API_KEY="sk-ant-..."    # For Anthropic API

PM2 for Persistent Tracking

# Start with PM2 (included in start-all.sh)
pm2 start claude-auto-track.js --name claude-track
pm2 save
pm2 startup

# Monitor
pm2 logs claude-track
pm2 status

Claude Workflow Configuration (.claude-instructions)

1. Regular Work - Normal conversation for code creation/editing
2. Session End - User says "recap" → Claude lists commands
3. Command Execution - User says "commit" → Claude executes commands

Manual Command Logging

# For testing or manual tracking
node track-claude-command.js <tool> <action> [params]

# Examples:
node track-claude-command.js Edit "Updated auth" file:auth.ts
node track-claude-command.js Bash "Run tests" command:"pnpm test"

🐛 Troubleshooting Claude Integration

Session Not Tracking

✅ Ensure ./start-all.sh is running
✅ Check PM2 status: pm2 status
✅ Verify .claude-commands.log exists
✅ Check API logs: tail -f apps/api/dev.log

Auto-Commit Not Working

✅ Click "Start Tracking" before working with Claude
✅ Select repository from dropdown
✅ Wait 3 seconds after ANY command for auto-task
✅ Check Git auth: git push origin main
✅ Auto-commit now triggers on ALL commands (not just file changes)
✅ Untracked files are automatically included with git add .

Common Fixes

# Clear Git lock
rm -f .git/index.lock

# Reset Claude tracking
pm2 restart claude-track

# Check system health
./check-system.sh

💻 Development

Development Commands

# Type checking
pnpm type-check

# Linting and formatting
pnpm lint
pnpm format

# Build all apps
pnpm build

# Run specific app
pnpm --filter web dev
pnpm --filter api dev

# Run tests
pnpm test

Database Commands

# Open Prisma Studio
cd apps/api && npx prisma studio

# Run migrations
cd apps/api && npx prisma migrate dev

# Reset database
cd apps/api && npx prisma migrate reset

# Generate Prisma client
cd apps/api && npx prisma generate

Utility Scripts

# User management
cd apps/api && npx tsx scripts/list-users.ts
cd apps/api && npx tsx scripts/create-test-user.ts

# Repository management
cd apps/api && npx tsx scripts/list-repositories.ts
cd apps/api && npx tsx scripts/cleanup-repo.ts
cd apps/api && npx tsx scripts/update-repo-paths.ts

# Task management
cd apps/api && npx tsx scripts/check-completed-tasks.ts

Environment Variables

See Environment Variables Guide for complete documentation.

Key variables:

ANTHROPIC_API_KEY - Claude API key or "claude" for CLI
DATABASE_URL - PostgreSQL connection string
NEXTAUTH_SECRET - Authentication secret
SMTP_* - Email configuration (optional)

🐛 Troubleshooting

🚧 Features Under Development

Notifications

The notification system is currently under development. While settings can be configured in the Settings → Notifications panel, the following features may not work as expected:

Desktop notifications
Sound notifications
Task completion alerts
Review request notifications

This feature will be fully implemented in a future release.

🔧 Quick Fixes

System Health Check

# Run comprehensive system check
./check-system.sh

Port Already in Use

# Kill processes on specific ports
lsof -ti:3000 | xargs kill -9  # Web server
lsof -ti:4000 | xargs kill -9  # API server

# Or use the stop script
./stop-all.sh

Module Not Found

# Clear cache and reinstall
rm -rf node_modules .turbo pnpm-lock.yaml
pnpm install

npm error "Unsupported URL Type workspace:"

# This project uses pnpm workspaces, not npm
# Install pnpm if not already installed
npm install -g pnpm

# Then use pnpm instead of npm
pnpm install

PM2 not installed

# PM2 is optional but recommended for Claude tracking
# Install globally with sudo
sudo npm install -g pm2

# Or install locally and use npx
npm install pm2
npx pm2 status

🗄️ Database Issues

Connection Failed

# Check PostgreSQL status
sudo service postgresql status

# Start PostgreSQL
sudo service postgresql start

# Verify connection
psql -U gitcraft -d gitcraft_studio -c "SELECT 1"

Migration Issues

# Reset database completely
./cleanup.sh --reset-db

# Manual reset
cd apps/api
npx prisma migrate reset --force
npx tsx scripts/init-db.ts

🤖 Claude Integration Issues

Session Not Tracking

# Check PM2 process
pm2 status

# Restart Claude tracker
pm2 restart claude-track

# Check log file exists
ls -la .claude-commands.log

# Monitor real-time logs
pm2 logs claude-track --lines 50

Auto-Commit Not Working

Verify Setup:
- ✅ Click "Start Tracking" before changes
- ✅ Select repository from dropdown
- ✅ Wait 3 seconds for auto-task creation

Check Git Status:

git remote -v     # Should show repository
git status        # Should show changes
git config --list # Check credentials

Monitor Logs:

# API server Git operations
tail -f apps/api/dev.log | grep -E "(Git|commit|push)"

# WebSocket events
# Check browser console for real-time events

Git Lock File Error

# Remove lock file
rm -f .git/index.lock

# If in repository subdirectory
find . -name "index.lock" -delete

🔐 Authentication Issues

Login Problems

Environment Variables:

# Verify matching secrets
grep NEXTAUTH_SECRET apps/api/.env
grep AUTH_SECRET apps/web/.env.local

Clear Session:

# Clear browser cookies
# Or in incognito mode

Create Initial User:

cd apps/api
# Create a new user with the signup API or through the web interface

GitHub Push Authentication

Personal Access Token Issues:

# Clear credentials
git config --global --unset credential.helper

# Set new helper
git config --global credential.helper store

# Test with new token
git push origin main
# Username: your-github-username
# Password: your-personal-access-token

SSH Key Issues:

# Test SSH connection
ssh -T git@github.com

# Add SSH key to agent
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

# Verify remote URL
git remote set-url origin git@github.com:username/repo.git

🌐 WebSocket Connection Issues

# Check WebSocket server
curl http://localhost:4000/debug/websocket

# Monitor connections
tail -f apps/api/dev.log | grep WebSocket

# Restart services
./stop-all.sh && ./start-all.sh

📝 Common Error Messages

Error	Solution
`EADDRINUSE`	Port in use, run `./stop-all.sh`
`ECONNREFUSED`	Database not running, start PostgreSQL
`Invalid token`	Clear cookies, login again
`Git push failed`	Check GitHub authentication
`Command not tracked`	Ensure PM2 claude-track is running
`Module not found`	Run `pnpm install`
`ai-service-dev not found`	File removed, imports updated

🆘 Still Having Issues?

Check Logs:

# All logs
tail -f apps/*/dev.log

# PM2 logs
pm2 logs

Reset Everything:

./cleanup.sh --all --reset-db
./init.sh
./start-all.sh

Report Issue:
- Check existing issues: GitHub Issues
- Include error logs and system info
- Mention steps to reproduce

📈 Current Status

✅ Fully Implemented

🔐 Authentication: NextAuth.js with email/password, password reset
📋 Task Management: 6-state workflow with priorities
🤖 AI Integration: 4 Claude models, streaming, context awareness
🔄 Real-time Features: WebSocket collaboration, cursor tracking
🗂️ Repository Management: GitHub integration, local repo support, path editing
🗄️ Database: PostgreSQL + Prisma ORM
⚙️ Settings: User preferences, tech stack templates
🌐 i18n: Complete English & Japanese interface
📖 Help System: Comprehensive 10-section documentation with search
📝 Claude Integration: Command tracking, auto-save, session browser
🚀 Auto Operations: Git commit/push from Claude sessions
🔧 Repository Path Management: Update repository paths in settings
🚫 Duplicate Prevention: Check for existing repositories before cloning

🚧 Roadmap

Complete remaining 6 help pages (Tasks, Claude AI, Git Operations, Settings, Collaboration, API Reference)
GitLab and Bitbucket integration
Team collaboration features
Advanced AI code analysis
Plugin system
Mobile app
CI/CD integration

🤝 Contributing

We welcome contributions! Please follow these steps:

Fork the repository
Create a feature branch:
```
git checkout -b feature/amazing-feature
```
Commit your changes:
```
git commit -m 'Add amazing feature'
```
Push to the branch:
```
git push origin feature/amazing-feature
```
Open a Pull Request

Development Guidelines

Follow TypeScript best practices
Write tests for new features
Update documentation
Ensure all checks pass

📈 Changelog

Latest Updates (2025-05-27)

📖 Comprehensive Help System: Added 10-section help documentation with search functionality
🌐 Complete i18n: Full Japanese & English translations for all help content
🔍 Advanced Search: Real-time filtering across all documentation
📱 Responsive Design: Mobile-optimized help pages with expandable sections
🎨 Enhanced UI: Modern help interface with copy-to-clipboard code blocks
🚀 Interactive Guides: Step-by-step installation and troubleshooting guides
🔧 Troubleshooting System: 6 common issues with expandable solutions and commands
📊 Quick Navigation: Help section overview with visual icons and descriptions
🗂️ Repository Directory Structure: Removed random ID generation, now uses repository name directly
📝 Repository Description: Fixed description field not being saved during creation/edit
🎌 Multi-language Support: Added output language selection (Japanese/English) for AI-generated content
🔧 Clone Directory Management: Added directory name field with automatic extraction from URL
📍 Clone Path Preview: Shows destination path before cloning
🔧 Repository Path Management: Added ability to update repository paths in settings
🚫 Duplicate Repository Check: Prevent cloning same repository multiple times
🗑️ Repository Deletion: Added delete functionality with proper cleanup
📝 Claude Workflow: Simplified commands - use "recap" and "commit"
🧹 Code Cleanup: Removed development-only files and updated naming conventions
🐛 Bug Fixes: Fixed import references to removed ai-service-dev files
🚀 Enhanced Auto-Git: Commands now trigger automatic Git commit/push
⚡ Faster Response: Reduced delay from 5s to 3s for command batching
📦 Include All Files: Untracked files automatically included with git add .
🎯 Universal Triggers: ALL commands trigger auto-commit (not just file changes)
🔄 Smart Batching: 30-second minimum between commits to prevent spam
📊 Better Descriptions: Comprehensive task descriptions with all command types

⚠️ Disclaimer

IMPORTANT: This software is provided "as is", without warranty of any kind, express or implied. The developers and contributors of GitCraft AI Studio assume no responsibility or liability for any damages, data loss, security breaches, or any other issues that may arise from using this software. Use at your own risk.

By using GitCraft AI Studio, you acknowledge that:

You are solely responsible for your code, data, and repository security
The automated Git operations may potentially cause data loss if not configured properly
AI-generated code should always be reviewed before deployment
You should maintain regular backups of your important code

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

🤖 Built with Claude AI assistance
💜 Powered by Anthropic's Claude API
🎨 UI components from shadcn/ui
🎯 Icons from Lucide React
🚀 Built with Next.js and tRPC

📞 Support

📖 Documentation: Built-in help system at /help
🐛 Issues: GitHub Issues
💬 Discussions: GitHub Discussions
📧 Email: yoshimasa.yamamoto@cruzy.jp

GitCraft AI Studio - Empowering developers with AI-driven Git workflows

Made with ❤️ by the GitCraft team

Name		Name	Last commit message	Last commit date
.claude		.claude
apps		apps
docs		docs
logo		logo
packages		packages
screenshots		screenshots
.env.example		.env.example
.gitignore		.gitignore
.nvmrc		.nvmrc
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
README.ja.md		README.ja.md
README.md		README.md
biome.json		biome.json
check-system.sh		check-system.sh
claude-hook.js		claude-hook.js
claude-integration-guide.md		claude-integration-guide.md
claude-tool-hook.sh		claude-tool-hook.sh
claude-track-manager.sh		claude-track-manager.sh
claude-wrapper.sh		claude-wrapper.sh
cleanup.sh		cleanup.sh
docker-compose.yml		docker-compose.yml
ecosystem.config.js		ecosystem.config.js
init.sh		init.sh
log-claude-command.js		log-claude-command.js
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
setup-claude-conversation-autosave.sh		setup-claude-conversation-autosave.sh
setup-env.sh		setup-env.sh
setup-github-auth.md		setup-github-auth.md
start-all.sh		start-all.sh
start-api.sh		start-api.sh
start-dev.sh		start-dev.sh
stop-all.sh		stop-all.sh
test-claude-integration.sh		test-claude-integration.sh
track-claude-command.js		track-claude-command.js
tsconfig.json		tsconfig.json
turbo.json		turbo.json

Latest commit

History

Folders and files

Repository files navigation

GitCraft AI Studio

📑 Table of Contents

📸 Screenshots

🖥️ User Interface

Dashboard Overview

Repository Management

Repository Details

Task Management

Claude Code Integration

Claude Code CLI

AI Assistant Settings

🏗️ Architecture & Workflow

Claude Integration Architecture

Claude Workflow

Command Tracking Flow

Auto-Commit and Push

Claude CLI Tools

Troubleshooting Flow

✨ Features

🎯 Core Features

🌐 Internationalization & User Experience

🤖 Claude Integration Features

🧠 AI Capabilities

🛠️ Tech Stack

Frontend

Backend

AI & Integrations

📋 Prerequisites

Required

Optional

🚀 Quick Start

1️⃣ Clone Repository

2️⃣ Install pnpm (if not already installed)

3️⃣ One-Command Setup

4️⃣ Environment Configuration

5️⃣ Start All Services

6️⃣ Access the Application

7️⃣ Verify Installation

📖 Documentation

📚 Built-in Help System

🔍 Search Functionality

📖 Complete Documentation Sections

🌐 Multi-language Support

🛠️ Interactive Features

📝 Key Help Sections

Getting Started

Installation & Setup

Repository Management

Troubleshooting

📦 PostgreSQL Setup (Manual)

🔧 System Management

Start/Stop Services

Service Management Details

Logs and Monitoring

Usage Guide

Task Workflow

Repository Management

Real-time Collaboration

🏗️ Project Structure

🔌 API Reference

Core API Endpoints (tRPC)

Authentication

Tasks

Repositories

Claude Sessions

Tech Stacks

WebSocket Events

Command Tracking

Collaboration

Utility Scripts

Database Management

Claude Integration

🚀 Initialization and Cleanup

Initial Setup (First Time Only)

🧹 Cleanup Procedures

Basic Cleanup (Keep Database)