rob
/
development-hub
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
development-hub/CLAUDE.md

251 lines
9.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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`.
Reference in New Issue View Git Blame Copy Permalink