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

9.9 KiB
Raw Blame History

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

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:

# 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.