# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

**Development Hub** is the central orchestration project for Rob's multi-project development ecosystem. It provides:

1. **GUI Application** - PyQt6-based workspace with project list, splittable terminal panes, and session persistence
2. **CLI Tools** - Scripts to create and manage projects following consistent patterns

## GUI Application

### Running the App

```bash
cd ~/PycharmProjects/development-hub
source .venv/bin/activate
python -m development_hub
```

### Architecture

```
src/development_hub/
├── __init__.py
├── __main__.py             # Entry point
├── app.py                  # QApplication subclass
├── main_window.py          # Main window with menus
├── project_list.py         # Left panel - project list with filter
├── workspace_manager.py    # Splittable pane layout management
├── pane_widget.py          # Tab container with action menu
├── draggable_tab_widget.py # Cross-pane tab dragging support
├── terminal_widget.py      # PTY terminal with search bar
├── terminal_display.py     # Terminal rendering with scrollback
├── pty_manager.py          # PTY process management
├── project_discovery.py    # Auto-discover projects from paths
├── dialogs.py              # New Project, Settings, Preview dialogs
├── settings.py             # JSON persistence for settings & session
├── styles.py               # Dark theme stylesheet
├── models/                 # Data models (Goal, Todo, Milestone)
├── views/dashboard/        # Dashboard views and components
│   ├── project_dashboard.py
│   ├── data_store.py       # Data loading/saving with file watching
│   └── undo_manager.py     # Undo/redo support
├── parsers/                # Markdown file parsers
├── services/               # Business logic (git, health, progress)
└── widgets/                # Reusable UI components
```

### Key Classes

| Class | File | Purpose |
|-------|------|---------|
| `MainWindow` | main_window.py | QMainWindow with menus, splitter layout |
| `ProjectListWidget` | project_list.py | Project list with filter and context menu |
| `WorkspaceManager` | workspace_manager.py | Manages splittable pane layout |
| `PaneWidget` | pane_widget.py | Tab container with action menu |
| `DraggableTabWidget` | draggable_tab_widget.py | Tab widget supporting cross-pane drag |
| `TerminalWidget` | terminal_widget.py | PTY terminal with search and auto-accept |
| `TerminalDisplay` | terminal_display.py | Terminal rendering with scrollback buffer |
| `AutoAcceptToast` | terminal_widget.py | Countdown toast for auto-accept prompts |
| `AutoAcceptDialog` | dialogs.py | Duration selection for auto-accept |
| `DashboardDataStore` | views/dashboard/data_store.py | Data persistence with file watching |
| `UndoManager` | views/dashboard/undo_manager.py | Undo/redo action management |

### Features

- **Project List**: Discovers projects from configurable search paths
- **Project Filtering**: Filter box to quickly find projects by name or key
- **Context Menu**: Open terminal, editor, Gitea, docs, deploy
- **Splittable Panes**: Horizontal/vertical splits, each pane has own tab bar
- **Cross-Pane Tab Dragging**: Drag tabs between panes to reorganize workspace
- **Terminal**: Full PTY with pyte for TUI support (vim, htop work)
- **Terminal Scrollback**: 10,000 line history with Shift+PageUp/Down navigation
- **Terminal Search**: Ctrl+Shift+F to search output with match highlighting
- **Terminal Error Recovery**: Graceful shell crash handling, Enter to restart
- **Drag & Drop**: Drop files/folders into terminal to inject paths
- **Session Persistence**: Remembers pane layout and open terminals
- **External File Watching**: Dashboard auto-reloads when files modified externally
- **New Project Dialog**: Integrates with Ramble for voice input
- **Progress Reports**: Export weekly progress summaries from daily standups
- **Auto-accept Prompts**: Automatically accept Y/yes prompts in terminals for CLI tools (Claude, Codex, etc.)

### Keyboard Shortcuts

#### Global Shortcuts

| Shortcut | Action |
|----------|--------|
| `Ctrl+Shift+T` | New terminal tab |
| `Ctrl+Shift+W` | Close current tab |
| `Ctrl+Shift+D` | Split pane horizontal |
| `Ctrl+Shift+E` | Split pane vertical |
| `Ctrl+Shift+P` | Close active pane |
| `Ctrl+Alt+Left/Right` | Switch panes |
| `Ctrl+B` | Toggle project panel |
| `Ctrl+N` | New project dialog |
| `Ctrl+D` | New discussion |
| `Ctrl+R` | Weekly progress report |
| `Ctrl+Z` | Undo (in dashboard) |
| `Ctrl+Shift+Z` | Redo (in dashboard) |
| `F5` | Refresh project list |

#### Terminal Shortcuts

| Shortcut | Action |
|----------|--------|
| `Ctrl+Shift+F` | Open search bar |
| `Ctrl+Shift+V` | Paste from clipboard |
| `Shift+PageUp/Down` | Scroll through history |
| `Enter` (in search) | Next match |
| `Shift+Enter` (in search) | Previous match |
| `F3` / `Shift+F3` | Next/previous match |
| `Escape` | Close search bar |

### Auto-accept Prompts

The terminal includes an auto-accept feature for handling Y/yes confirmation prompts from CLI tools like Claude Code, Codex, etc. This is useful when running long-running AI tasks that may ask many permission questions.

**How to use:**
1. Click ☰ (action menu) → "Auto-accept prompts..."
2. Select a duration (5 min, 15 min, 30 min, 1 hour, or custom)
3. When a Y/yes prompt is detected, a toast appears with a 5-second countdown
4. Click "Skip" to ignore, "Accept" to confirm immediately, or wait for countdown
5. Tab badge shows remaining time (e.g., `⏱4:32`)
6. Click ☰ → "Stop auto-accept" to disable early

**Supported patterns:**
- Standard `[Y/n]`, `[y/N]`, `(y/n)` prompts
- Claude Code permission dialogs with `❯ 1. Yes` menu selection

#### Dashboard Shortcuts (when dashboard tab is active)

| Shortcut | Action |
|----------|--------|
| `/` | Focus add todo input |
| `Ctrl+1` | Switch to priority view |
| `Ctrl+2` | Switch to milestone view |
| `Ctrl+3` | Switch to show all view |
| `Ctrl+]` | Expand all sections |
| `Ctrl+[` | Collapse all sections |

### Dashboard Data Sync

The dashboard automatically syncs data between documentation files:

- **Deliverables → TODOs**: When loading a project dashboard, deliverables from `milestones.md` tables are synced to `todos.md`. If a deliverable doesn't exist as a todo (matched by text + milestone ID), it's added with the appropriate `@M#` tag and priority.
- **TODOs → Milestone Progress**: The milestone progress bar is calculated from linked todos (items tagged with `@M#`), not from the deliverables table.

This means you can define major work items in milestone deliverable tables, and they'll automatically appear in your todo list for tracking.

## CLI Scripts

### `bin/new-project`

Creates a new project in the ecosystem with all the standard setup:

```bash
# Full usage
new-project myproject --title "My Project" --tagline "Short description"

# Interactive mode (prompts for title/tagline)
new-project myproject

# Options
--title "..."     Display title for the project
--tagline "..."   Short description
--dry-run         Show what would happen without making changes
--skip-gitea      Skip Gitea repository creation (for offline use)
```

**What it does:**
1. Creates Gitea repository via API
2. Creates local project directory with git
3. Generates project files from templates (CLAUDE.md, README.md, .gitignore, pyproject.toml)
4. Sets up documentation symlink to project-docs
5. Updates build-public-docs.sh to include the new project
6. Creates initial commit and pushes

## Project Structure

```
development-hub/
├── src/development_hub/      # GUI application (see Architecture above)
├── bin/
│   └── new-project           # CLI scaffolding script
├── templates/
│   ├── gitignore.template    # Python .gitignore with docs exclusion
│   ├── CLAUDE.md.template    # AI context file
│   ├── README.md.template    # Basic README
│   ├── pyproject.toml.template
│   ├── overview.md.template  # Docs overview
│   └── updating-documentation.md.template
├── docs/                     # Symlink to project-docs
├── pyproject.toml            # Python packaging with PyQt6 dep
├── CLAUDE.md                 # This file
├── README.md
└── .gitignore
```

## Template Placeholders

Templates use these placeholders (replaced by sed):

- `{{PROJECT_NAME}}` - lowercase project name (e.g., "my-tool")
- `{{PROJECT_TITLE}}` - display title (e.g., "My Tool")
- `{{PROJECT_TAGLINE}}` - short description
- `{{YEAR}}` - current year
- `{{DATE}}` - creation date
- `{{GITEA_URL}}` - https://gitea.brrd.tech
- `{{GITEA_OWNER}}` - rob

## Configuration

### Gitea API Token

The script needs a Gitea API token to create repositories:

1. **Environment variable**: `GITEA_TOKEN`
2. **Config file**: `~/.config/development-hub/gitea-token`

To create a token:
1. Go to https://gitea.brrd.tech/user/settings/applications
2. Generate a new token with 'repo' scope
3. The script will prompt and save it automatically

## Documentation

Documentation lives in the centralized docs system:

- **Source**: `~/PycharmProjects/project-docs/docs/projects/development-hub/`
- **Public URL**: `https://pages.brrd.tech/rob/development-hub/`

When updating documentation:
1. Edit files in `docs/` (the symlink)
2. Use `public: true` frontmatter for public-facing docs
3. Run `~/PycharmProjects/project-docs/scripts/build-public-docs.sh development-hub --deploy` to publish

## Related Projects

This project manages and creates projects in the ecosystem:

- **CmdForge** - AI-powered CLI tool builder
- **CascadingDev** - Cascading Development Framework
- **Orchestrated Discussions** - AI Discussion Framework
- **Artifact Editor** - Code Artifact Editor
- **Ramble** - Voice Note Transcription

All projects follow the same documentation pattern and can be created using `new-project`.