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

15 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, Setup Wizard dialogs
├── settings.py             # JSON persistence for settings & session
├── paths.py                # Centralized path resolution from settings
├── 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
ImportPlanDialog dialogs.py Import implementation plans to milestones
SetupWizardDialog dialogs.py Multi-page first-run wizard
SettingsDialog dialogs.py Application settings with docs mode
PathResolver paths.py Centralized path resolution singleton
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, git host, docs, deploy (items hidden when not configured)
  • 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.)
  • Plan Import: Import implementation plans into milestones via right-click context menu
  • Phase Grouping: Todos can be grouped by phase within milestones using [Phase N] prefix
  • Milestone Discussions: Start discussions directly from milestones for implementation planning
  • Workspace Files: Export/import configuration via YAML for sharing setups
  • First-Run Wizard: Multi-page setup wizard with Simple/Documentation/Import modes
  • Documentation Modes: Standalone (local storage) or Project-Docs (Docusaurus integration)
  • Graceful Degradation: Features hide when dependencies unavailable (CmdForge, git, docs)

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+G Global Dashboard
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.

Todo Notes

Todos can have optional notes that provide additional context. Notes are displayed as tooltips when hovering over todo items and are persisted as indented blockquote lines in todos.md:

- [ ] [Phase 1] Add settings module @M4
  > File: settings.py - Add DEFAULTS and properties
- [ ] Task without notes @M4

Notes are automatically extracted when importing plans via the Import Plan dialog and preserved through save/reload cycles.

Workspace Files

Development Hub supports exporting and importing configuration via YAML workspace files. This allows sharing setups between machines or users.

Export/Import via menu: File → Export Workspace... / Import Workspace...

Workspace file format:

# ~/.devhub-workspace.yaml
name: "My Development Environment"
version: 1

paths:
  projects_root: ~/PycharmProjects
  docs_root: ~/PycharmProjects/project-docs/docs  # Optional

documentation:
  enabled: true
  mode: project-docs  # "standalone" | "project-docs"
  docusaurus_path: ~/PycharmProjects/project-docs
  auto_start_server: true

git_hosting:
  type: gitea  # "gitea" | "github" | "gitlab"
  url: https://gitea.example.com
  owner: username
  pages_url: https://pages.example.com  # Optional

features:
  cmdforge_integration: true
  progress_tracking: true

Documentation Modes

Development Hub supports two documentation modes:

  1. Standalone Mode: Data stored locally in ~/.local/share/development-hub/. No Docusaurus integration. Good for simple use cases.

  2. Project-Docs Mode: Full Docusaurus integration with centralized documentation. Supports auto-start docs server, deploy scripts, and pages hosting.

The mode is configured during first-run setup or in Settings → Documentation.

First-Run Wizard

On first launch (when no settings.json exists), the setup wizard appears with three options:

  1. Simple Mode: Quick setup with just a projects directory. Documentation features disabled.
  2. Documentation Mode: Full setup with Docusaurus path, git hosting, and pages configuration.
  3. Import Workspace: Load settings from a .devhub-workspace.yaml file.

Existing users are unaffected - the wizard only appears when setup_completed is false.

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

Settings File

Settings are stored in ~/.config/development-hub/settings.json. Key settings:

Setting Default Description
docs_mode "auto" "auto", "standalone", or "project-docs"
docs_root "" Override docs root path (empty = derive from mode)
docusaurus_path "" Path to project-docs directory
pages_url "" URL for documentation pages hosting
cmdforge_path "" Override CmdForge installation path
progress_dir "" Override progress log directory
auto_start_docs_server true Start Docusaurus dev server on launch
git_host_type "" "gitea", "github", or "gitlab"
git_host_url "" Git hosting URL
git_host_owner "" Username or organization
git_host_token "" API token for repo creation

Path Resolution

The PathResolver class (paths.py) centralizes all path lookups:

from development_hub.paths import paths

paths.projects_root      # Primary projects directory
paths.docs_root          # Documentation root
paths.project_docs_dir   # Docusaurus project directory
paths.progress_dir       # Progress log directory
paths.build_script       # build-public-docs.sh path
paths.cmdforge_executable  # CmdForge binary path

paths.project_docs_path("myproject")  # Docs for specific project
paths.git_url("owner", "repo")        # Git repository URL
paths.pages_url("owner", "repo")      # Pages URL for project

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.