|
1 | 1 | # charmer |
2 | 2 |
|
3 | | -A terminal user interface (TUI) for monitoring Snakemake pipelines running on HPC clusters. |
| 3 | +A terminal user interface (TUI) for monitoring Snakemake pipelines on HPC clusters. |
4 | 4 |
|
5 | 5 |  |
6 | 6 |
|
7 | 7 | ## Features |
8 | 8 |
|
9 | | -- **Real-time monitoring** of Snakemake pipelines on SLURM and LSF clusters |
10 | | -- **Unified view** merging data from scheduler queries and Snakemake metadata |
11 | | -- **Interactive TUI** with vim-style navigation |
12 | | -- **Filtering & sorting** by job status, rule name, or time |
13 | | -- **Log viewer** for examining job output |
14 | | -- **Cross-platform** support for Linux and macOS |
| 9 | +- Real-time monitoring of Snakemake pipelines on SLURM and LSF clusters |
| 10 | +- Interactive TUI with vim-style navigation |
| 11 | +- Filtering, sorting, and log viewing |
15 | 12 |
|
16 | 13 | ## Installation |
17 | 14 |
|
18 | | -### From source |
19 | | - |
20 | 15 | ```bash |
21 | | -# Clone the repository |
22 | | -git clone https://github.com/rnabioco/charmer.git |
23 | | -cd charmer |
24 | | - |
25 | | -# Build with cargo |
26 | | -cargo build --release |
27 | | - |
28 | | -# Install to ~/.cargo/bin |
29 | | -cargo install --path crates/charmer |
| 16 | +cargo install --git https://github.com/rnabioco/charmer.git |
30 | 17 | ``` |
31 | 18 |
|
32 | | -### Using pixi (for development) |
33 | | - |
34 | | -```bash |
35 | | -pixi install |
36 | | -pixi run build |
37 | | -``` |
38 | | - |
39 | | -## Usage |
| 19 | +## Quick Start |
40 | 20 |
|
41 | 21 | ```bash |
42 | 22 | # Monitor current directory |
43 | 23 | charmer |
44 | 24 |
|
45 | 25 | # Monitor specific directory |
46 | 26 | charmer /path/to/pipeline |
47 | | - |
48 | | -# With options |
49 | | -charmer --poll-interval 10 --theme dark /path/to/pipeline |
50 | 27 | ``` |
51 | 28 |
|
52 | | -### CLI Options |
53 | | - |
54 | | -| Option | Default | Description | |
55 | | -|--------|---------|-------------| |
56 | | -| `--poll-interval` | 5 | Seconds between scheduler queries | |
57 | | -| `--run-uuid` | - | Filter to specific Snakemake run | |
58 | | -| `--theme` | dark | Color theme (dark/light) | |
59 | | -| `--history-hours` | 24 | Show completed jobs from last N hours | |
60 | | - |
61 | | -### Keyboard Shortcuts |
62 | | - |
63 | | -| Key | Action | |
64 | | -|-----|--------| |
65 | | -| `j` / `β` | Move down | |
66 | | -| `k` / `β` | Move up | |
67 | | -| `g` / `Home` | Go to first job | |
68 | | -| `G` / `End` | Go to last job | |
69 | | -| `f` | Cycle filter (All/Running/Failed/Pending/Completed) | |
70 | | -| `s` | Cycle sort (Status/Rule/Time) | |
71 | | -| `l` / `Enter` | View job logs | |
72 | | -| `F` | Toggle follow mode in logs | |
73 | | -| `?` | Show help | |
74 | | -| `q` / `Ctrl+C` | Quit | |
75 | | - |
76 | | -## Supported Schedulers |
77 | | - |
78 | | -### SLURM |
79 | | - |
80 | | -Charmer queries SLURM using: |
81 | | -- `squeue` for active jobs |
82 | | -- `sacct` for job history |
83 | | - |
84 | | -Jobs are correlated with Snakemake using the comment field format: |
85 | | -`rule_{rulename}_wildcards_{wildcards}` |
86 | | - |
87 | | -### LSF |
88 | | - |
89 | | -Charmer queries LSF using: |
90 | | -- `bjobs` for active jobs |
91 | | -- `bhist` for job history |
| 29 | +## Documentation |
92 | 30 |
|
93 | | -## How It Works |
94 | | - |
95 | | -Charmer combines data from multiple sources: |
96 | | - |
97 | | -1. **Snakemake metadata** (`.snakemake/metadata/`) - Job inputs, outputs, shell commands |
98 | | -2. **Scheduler queries** - Job status, resource usage, timing |
99 | | -3. **Log files** (`.snakemake/slurm_logs/`) - Job output and errors |
100 | | - |
101 | | -Data is merged using rule names and timing windows to correlate jobs across sources. |
102 | | - |
103 | | -## Development |
104 | | - |
105 | | -```bash |
106 | | -# Install dependencies |
107 | | -pixi install |
108 | | - |
109 | | -# Run tests |
110 | | -cargo test |
111 | | - |
112 | | -# Run with debug logging |
113 | | -RUST_LOG=debug cargo run -- . |
114 | | - |
115 | | -# Build documentation |
116 | | -pixi run docs |
117 | | -``` |
118 | | - |
119 | | -### Project Structure |
120 | | - |
121 | | -``` |
122 | | -charmer/ |
123 | | -βββ crates/ |
124 | | -β βββ charmer/ # Main binary |
125 | | -β βββ charmer-cli/ # CLI argument parsing |
126 | | -β βββ charmer-core/ # Snakemake metadata parsing |
127 | | -β βββ charmer-slurm/ # SLURM integration |
128 | | -β βββ charmer-lsf/ # LSF integration |
129 | | -β βββ charmer-state/ # Unified job state |
130 | | -β βββ charmer-monitor/ # TUI components |
131 | | -βββ docs/ # Documentation |
132 | | -βββ tests/ # Integration tests |
133 | | -``` |
| 31 | +Full documentation is available at **[rnabioco.github.io/charmer](https://rnabioco.github.io/charmer)**. |
134 | 32 |
|
135 | 33 | ## License |
136 | 34 |
|
137 | 35 | MIT License - see [LICENSE](LICENSE) for details. |
138 | | - |
139 | | -## Contributing |
140 | | - |
141 | | -Contributions welcome! Please read our [contributing guide](CONTRIBUTING.md) first. |
0 commit comments