docs: update documentation and fix lint issues for v1.0.0
Documentation: - Rewrite README.md with current features and git operations - Rewrite docs/ARCHITECTURE.md with layered architecture details - Rewrite docs/tui-ide-spec.md with Alt-key shortcuts - Add docs/code-organization.md for component architecture - Add docs/user-manual.md for end users - Update TODO.md to mark completed items Code fixes: - Fix undefined 'event' variable in diff_pane.py (was _event) - Use ternary operator in editor.py save_file method - Clean up imports in claude_events.py and syntax_service.py - Auto-fix import sorting across multiple files Config: - Add snapshot report path to pyproject.toml pytest options - Exclude clide/vendor from ruff linting - Ignore TCH002/TCH003 type-checking import rules Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Jeroen Schweitzer
co-authored by
Claude Opus 4.5
Claude Opus 4.5
parent
2d2e5f5648
commit
8b1a84e7e2
@@ -0,0 +1,398 @@
|
||||
# Clide User Manual
|
||||
|
||||
Clide is a terminal-based IDE that puts Claude Code at the center of your development workflow. This manual covers installation, daily usage, and customization.
|
||||
|
||||
## Installation
|
||||
|
||||
### Requirements
|
||||
|
||||
- Python 3.12 or later
|
||||
- Git
|
||||
- Claude Code CLI installed and authenticated
|
||||
|
||||
### Setup
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone <repo-url>
|
||||
cd clide
|
||||
|
||||
# Install dependencies and create virtual environment
|
||||
make setup
|
||||
|
||||
# Run Clide
|
||||
make run
|
||||
```
|
||||
|
||||
Or install directly:
|
||||
|
||||
```bash
|
||||
pip install -e .
|
||||
clide
|
||||
```
|
||||
|
||||
### First Run
|
||||
|
||||
On first launch, Clide creates a configuration directory at `~/.clide/` for user settings. Project-specific settings are stored in `.clide/` within your project.
|
||||
|
||||
## Interface Overview
|
||||
|
||||
```
|
||||
┌─────────────────┬─────────────────────────┬──────────────────┐
|
||||
│ Sidebar │ Workspace │ Context │
|
||||
│ │ [Editor][Diff][Terminal]│ │
|
||||
│ [Files][Git] │ (appears when needed) │ [Jira][TODOs] │
|
||||
│ [Tree] ├─────────────────────────┤ [Problems] │
|
||||
│ │ │ │
|
||||
│ │ Claude │ │
|
||||
│ │ (always visible) │ │
|
||||
│ │ │ │
|
||||
├─────────────────┤ ├──────────────────┤
|
||||
│ ⎇ main ▾ │ │ │
|
||||
│ staged: 2 │ │ │
|
||||
└─────────────────┴─────────────────────────┴──────────────────┘
|
||||
```
|
||||
|
||||
### Panels
|
||||
|
||||
**Left Sidebar** — File browser, git changes, and branch graph
|
||||
|
||||
**Center** — Claude Code (always visible) and workspace panels (editor, diff, terminal) that appear when needed
|
||||
|
||||
**Right Context** — Jira integration, TODO list, and problems from linters
|
||||
|
||||
## Keyboard Shortcuts
|
||||
|
||||
All shortcuts use `Alt` as the modifier to avoid conflicts with Claude Code input.
|
||||
|
||||
### Panel Navigation
|
||||
|
||||
| Action | Shortcut |
|
||||
|--------|----------|
|
||||
| Toggle left sidebar | `Alt+B` |
|
||||
| Toggle right sidebar | `Alt+Shift+B` |
|
||||
| Toggle terminal | `` Alt+` `` |
|
||||
| Focus Claude | `Alt+1` |
|
||||
| Focus Editor | `Alt+2` |
|
||||
| Focus Terminal | `Alt+3` |
|
||||
| Toggle compact mode | `Alt+C` |
|
||||
|
||||
### File Operations
|
||||
|
||||
| Action | Shortcut |
|
||||
|--------|----------|
|
||||
| Quick open file | `Alt+O` |
|
||||
| Save file | `Alt+S` |
|
||||
| Go to line | `Alt+L` |
|
||||
|
||||
### Git Operations
|
||||
|
||||
| Action | Shortcut |
|
||||
|--------|----------|
|
||||
| Open Git panel | `Alt+G` |
|
||||
| Open Problems panel | `Alt+M` |
|
||||
|
||||
### Application
|
||||
|
||||
| Action | Shortcut |
|
||||
|--------|----------|
|
||||
| Command palette | `Alt+P` |
|
||||
| Select theme | `Alt+T` |
|
||||
| Quit | `Alt+Q` |
|
||||
|
||||
## Working with Claude
|
||||
|
||||
Claude Code runs in the center panel and is always visible. Type your prompts directly and Claude will respond with code suggestions, explanations, and file operations.
|
||||
|
||||
### Git Integration
|
||||
|
||||
The sidebar includes buttons for common git operations that delegate to Claude:
|
||||
|
||||
- **Commit** — Claude reviews staged changes and creates a well-formatted commit
|
||||
- **Stash** — Claude stashes your working changes
|
||||
- **Pull** — Claude pulls with rebase and helps resolve conflicts
|
||||
- **Push** — Claude pushes to remote, setting upstream if needed
|
||||
|
||||
On first use, Clide installs the corresponding skill to your project's `.claude/skills/` directory. These skills guide Claude through each operation following best practices.
|
||||
|
||||
### Branch Status
|
||||
|
||||
The branch status bar at the bottom of the sidebar shows:
|
||||
|
||||
- Current branch name
|
||||
- Staged and unstaged file counts
|
||||
|
||||
Click the branch name to open the branch selector:
|
||||
|
||||
```
|
||||
┌─────────────────┐
|
||||
│ Recent branches │
|
||||
│ ● main │
|
||||
│ ○ feature/xyz │
|
||||
│ ○ develop │
|
||||
├─────────────────┤
|
||||
│[Checkout] [New] │
|
||||
└─────────────────┘
|
||||
```
|
||||
|
||||
## Left Sidebar
|
||||
|
||||
### Files Tab
|
||||
|
||||
Browse your project structure. Click a file to open it in the editor.
|
||||
|
||||
- Directories expand/collapse on click
|
||||
- Hidden files (starting with `.`) are shown but dimmed
|
||||
- Noisy directories (`.git`, `__pycache__`, `node_modules`) are filtered
|
||||
|
||||
### Git Tab
|
||||
|
||||
View staged and unstaged changes:
|
||||
|
||||
```
|
||||
Staged (2)
|
||||
+ src/new_file.py
|
||||
~ src/modified.py
|
||||
|
||||
Unstaged (3)
|
||||
~ README.md
|
||||
? untracked.txt
|
||||
- deleted.py
|
||||
```
|
||||
|
||||
**Status indicators:**
|
||||
- `+` Added
|
||||
- `~` Modified
|
||||
- `-` Deleted
|
||||
- `?` Untracked
|
||||
- `→` Renamed
|
||||
|
||||
Click a file to view its diff. Use the action buttons to commit, stash, pull, or push via Claude.
|
||||
|
||||
### Tree Tab
|
||||
|
||||
Visual git graph showing branch history:
|
||||
|
||||
```
|
||||
● main: Latest commit message
|
||||
│
|
||||
├─● feature: Feature work
|
||||
│
|
||||
●─┴ Merge branch 'feature'
|
||||
```
|
||||
|
||||
**Commit types:**
|
||||
- `●` Regular commit
|
||||
- `◆` Merge commit
|
||||
|
||||
## Right Context Panel
|
||||
|
||||
### Jira Tab
|
||||
|
||||
Displays Jira issues when configured. Click the refresh button to update.
|
||||
|
||||
Configure Jira integration in settings:
|
||||
|
||||
```json
|
||||
{
|
||||
"jira_enabled": true,
|
||||
"jira_cli_path": "jira"
|
||||
}
|
||||
```
|
||||
|
||||
### TODOs Tab
|
||||
|
||||
Scans your codebase for TODO comments and project tasks.
|
||||
|
||||
**Sub-tabs:**
|
||||
|
||||
- **Project** — Items from `TODO.md` (checkbox format)
|
||||
- **Comments** — TODO/FIXME/HACK/XXX comments in code
|
||||
|
||||
Click an item to jump to that location in the editor.
|
||||
|
||||
**Supported comment markers:**
|
||||
- `TODO` — Tasks to complete
|
||||
- `FIXME` — Bugs to fix
|
||||
- `HACK` — Temporary solutions
|
||||
- `XXX` — Dangerous or problematic code
|
||||
- `NOTE` — Important notes
|
||||
- `BUG` — Known bugs
|
||||
|
||||
### Problems Tab
|
||||
|
||||
Displays linter errors and warnings. Click a problem to jump to the source location.
|
||||
|
||||
## Workspace Panels
|
||||
|
||||
The workspace appears when you need to view or edit files. It contains three tabs:
|
||||
|
||||
### Editor
|
||||
|
||||
Full-featured code editor with:
|
||||
|
||||
- Syntax highlighting (Python, JavaScript, TypeScript, HTML, CSS, JSON, YAML, Markdown, and more)
|
||||
- Line numbers
|
||||
- Current line highlighting
|
||||
|
||||
### Diff
|
||||
|
||||
Side-by-side diff viewer for reviewing changes. Used when:
|
||||
|
||||
- Viewing git changes
|
||||
- Reviewing Claude's proposed edits
|
||||
|
||||
### Terminal
|
||||
|
||||
Command-line terminal for running commands. Output is preserved when the panel is hidden.
|
||||
|
||||
## Themes
|
||||
|
||||
Clide includes 22 built-in themes. Press `Alt+T` to open the theme selector.
|
||||
|
||||
**Theme categories:**
|
||||
|
||||
| Category | Themes |
|
||||
|----------|--------|
|
||||
| Core | summer-night (default), summer-day |
|
||||
| Popular | one-dark, one-dark-pro, one-light, dracula, nord, gruvbox-dark, gruvbox-light |
|
||||
| Seasonal | winter-is-coming, monokai-winter, fall, dark-autumn |
|
||||
| Halloween | all-hallows-eve, halloween |
|
||||
| Christmas | christmas, santa-baby |
|
||||
| Hacker | pro-hacker, hacker-style |
|
||||
| Other | gamma, one-dark-teal, houston |
|
||||
|
||||
Your theme choice is saved and persists across sessions.
|
||||
|
||||
### Custom Themes
|
||||
|
||||
Create custom themes in `~/.clide/themes/`:
|
||||
|
||||
```toml
|
||||
# ~/.clide/themes/my-theme.toml
|
||||
name = "my-theme"
|
||||
display_name = "My Custom Theme"
|
||||
dark = true
|
||||
|
||||
[colors]
|
||||
primary = "#007acc"
|
||||
secondary = "#3c3c3c"
|
||||
accent = "#0e639c"
|
||||
background = "#1e1e1e"
|
||||
surface = "#252526"
|
||||
panel = "#2d2d30"
|
||||
foreground = "#d4d4d4"
|
||||
success = "#4ec9b0"
|
||||
warning = "#dcdcaa"
|
||||
error = "#f44747"
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### User Settings
|
||||
|
||||
Settings are stored in `~/.clide/settings.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"theme": "summer-night",
|
||||
"compact_mode": false,
|
||||
"jira_enabled": false,
|
||||
"jira_cli_path": "jira"
|
||||
}
|
||||
```
|
||||
|
||||
### Project Settings
|
||||
|
||||
Project-specific settings in `.clide/`:
|
||||
|
||||
```
|
||||
.clide/
|
||||
├── settings.json # Project overrides
|
||||
└── skills/ # Installed Claude skills
|
||||
├── commit/
|
||||
├── stash/
|
||||
└── ...
|
||||
```
|
||||
|
||||
### Environment Variables
|
||||
|
||||
Override settings with environment variables prefixed with `CLIDE_`:
|
||||
|
||||
```bash
|
||||
CLIDE_THEME=dracula clide
|
||||
```
|
||||
|
||||
## Compact Mode
|
||||
|
||||
Press `Alt+C` to toggle compact mode, which hides both sidebars for focused work. All panel state is preserved—nothing is lost when hiding panels.
|
||||
|
||||
## Project TODOs
|
||||
|
||||
Clide integrates with a `TODO.md` file in your project root. Format:
|
||||
|
||||
```markdown
|
||||
# TODO
|
||||
|
||||
## Features
|
||||
|
||||
- [ ] Implement user authentication
|
||||
- [ ] Add search functionality
|
||||
- [x] Set up database connection
|
||||
|
||||
## Bugs
|
||||
|
||||
- [ ] Fix login redirect
|
||||
```
|
||||
|
||||
Items appear in the TODOs panel, grouped by section. Click to jump to that line. Check off items directly in the file.
|
||||
|
||||
If no `TODO.md` exists, click "Create TODO.md" in the TODOs panel to generate a template.
|
||||
|
||||
## Tips
|
||||
|
||||
### Efficient Navigation
|
||||
|
||||
1. Use `Alt+1/2/3` to quickly switch between Claude, Editor, and Terminal
|
||||
2. Click items in Problems or TODOs to jump directly to source
|
||||
3. Use compact mode (`Alt+C`) when you need more space for Claude
|
||||
|
||||
### Git Workflow
|
||||
|
||||
1. Make changes to your code
|
||||
2. Review changes in the Git tab
|
||||
3. Click "Commit" to have Claude create a well-formatted commit
|
||||
4. Use "Push" when ready to share
|
||||
|
||||
### Working with Claude
|
||||
|
||||
- Claude sees your project context automatically
|
||||
- Use the git action buttons for consistent commit messages
|
||||
- Click files in the sidebar to show Claude what you're working on
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Claude Code not starting
|
||||
|
||||
Ensure Claude Code CLI is installed and authenticated:
|
||||
|
||||
```bash
|
||||
claude --version
|
||||
claude auth status
|
||||
```
|
||||
|
||||
### Theme not applying
|
||||
|
||||
Check that the theme name in settings matches exactly. Theme names are case-sensitive.
|
||||
|
||||
### Skills not working
|
||||
|
||||
Skills are installed to `.claude/skills/` in your project. If a skill fails:
|
||||
|
||||
1. Check that the skill folder exists
|
||||
2. Verify `SKILL.md` is present
|
||||
3. Try removing and re-triggering the action
|
||||
|
||||
### Panels not updating
|
||||
|
||||
Try refreshing with the relevant shortcut or clicking the refresh button. File changes should update automatically via file watching.
|
||||
Reference in New Issue
Block a user