# Paneship
[](https://crates.io/crates/paneship)
[](https://docs.rs/paneship)
[](https://opensource.org/licenses/MIT)
[](https://github.com/andev0x/paneship)
[](https://github.com/andev0x/paneship/actions)
[](https://github.com/andev0x/paneship/stargazers)
[](https://github.com/andev0x/paneship/releases)
A high-performance shell prompt written in Rust, optimized for tmux environments, large Git repositories, and developers who value speed and clarity.
## Demo
<div align="center">
<img src="https://raw.githubusercontent.com/andev0x/description-image-archive/refs/heads/main/paneship/paneship.png" width="80%" alt="Paneship" />
</div>
## Overview
**Paneship** is a fast, modern shell prompt that displays essential workspace information at a glance. With a persistent background daemon, asynchronous metadata updates, and an optimized socket-based rendering pipeline, it renders in **~1.5ms** on averageβenabling snappy shell interactions without sacrificing functionality.
### Key Metrics
- **Average render time**: ~1.5ms per prompt
- **Performance**: Up to ~10x faster than comparable alternatives
- **Daemon-side rendering**: Client-only overhead is minimal (~0.5ms socket call)
- **Async Background Refreshes**: Git and metadata updates never block your prompt
- **Smart Invalidation**: Triggered by Git HEAD changes and shell exit codes
## Features
- **β‘ Ultra-fast rendering** β ~1.5ms average by offloading all logic to a persistent background daemon
- **π Async Background Worker** β Heavy operations (Git status, language versions) run in a separate thread and never block the renderer
- **π― Tmux-aware** β Automatic pane width detection, responsive truncation, and zero-lag cross-pane cache sharing
- **π§ Rich Git integration** β Branch display and file counts using `gix`, with smart refreshes on commit/branch switch
- **π’ Language & Metadata** β Automatic detection for Rust, Node.js, Python, Go, and more; version info is fetched asynchronously
- **β±οΈ Command timing** β Shows last command duration in human-readable format (ms/s/m)
- **ποΈ Fully customizable** β Simple TOML config for colors, icons, and layout
- **π Safe & Efficient** β Written in Rust with a minimal resource footprint and system allocator for fast startup
## Quick Start
### Installation
Install the latest release from [crates.io](https://crates.io/crates/paneship):
```bash
cargo install paneship
```
Or build from source:
```bash
git clone https://github.com/andev0x/paneship.git
cd paneship
cargo install --path .
```
### Setup
#### Zsh (Recommended)
Add the following line to your `~/.zshrc`:
```bash
eval "$(paneship init zsh)"
```
Then restart your shell:
```bash
exec zsh
```
Or reload your configuration:
```bash
source ~/.zshrc
```
#### Other Shells
Support for Bash, Fish, and other shells is planned. For now, you can manually integrate Paneship by:
1. Setting your prompt variable to call `paneship render`
2. Capturing the last command exit code
3. (Optional) Setting `COLUMNS` to your terminal width for responsive layout
Example for Bash (basic setup):
```bash
PROMPT_COMMAND='PROMPT="$(paneship render --exit-code $? --width $COLUMNS)"'
```
## Prompt Layout
Paneship displays a two-line prompt:
```
ο» ~/.../paneship ξ main ~2 Β· π¦ v1.0.0 π¦ 1.95.0 σ° 11ms σ°₯ 20:56
β―
```
### Line 1 Breakdown
**Left side (Context):**
- **Directory**: Project-aware path truncation (shows repository root + relative path)
- **Git branch**: Current branch name with icon
- **Git status**: Icons for staged (`+`), unstaged (`~`), and untracked (`?`) changes
- **Package version**: Extracted from Cargo.toml, package.json, pyproject.toml, etc.
**Right side (Metadata):**
- **Language & version**: Detected language with runtime version (e.g., `π¦ Rust 1.75`)
- **Command duration**: Time taken by the last command (e.g., `σ° 125ms`)
- **Current time**: HH:MM format
### Line 2
A single cursor character (customizable via config).
## Configuration
Paneship reads its configuration from `~/.config/paneship/config.toml`. If no config file exists, sensible defaults are used.
### Example Configuration
```toml
[directory]
icon = "π"
truncation_length = 3
truncate_to_repo = true
[git]
branch_icon = ""
staged_icon = "+"
unstaged_icon = "~"
untracked_icon = "?"
[status]
success_icon = "β―"
failure_icon = "β―"
[metadata]
time_color = "2;37"
paneship_color = "1;32"
[metadata.languages.rust]
icon = "π¦"
color = "1;33"
[metadata.languages.node]
icon = "β¬’"
color = "1;32"
```
### Configuration Options
#### Directory
- `icon` β Symbol displayed before the directory path (default: `""`βfolder icon)
- `truncation_length` β Number of path components to show before truncating (default: `3`)
- `truncate_to_repo` β Show only repository name + truncated path inside repos (default: `true`)
#### Git
- `branch_icon` β Symbol before branch name (default: `""`)
- `staged_icon` β Symbol for staged changes (default: `"+"`)
- `unstaged_icon` β Symbol for unstaged changes (default: `"~"`)
- `untracked_icon` β Symbol for untracked files (default: `"?"`)
#### Status
- `success_icon` β Cursor symbol for successful exit (default: `"β―"`)
- `failure_icon` β Cursor symbol for failed exit (default: `"β―"`)
#### Metadata
- `time_color` β ANSI color code for time display (default: `"2;37"`)
- `paneship_color` β ANSI color code for metadata (default: `"1;32"`)
- `languages.<name>` β Language-specific configuration (icon and color)
## Architecture
### Daemon-Driven Model
Paneship uses a client-daemon architecture to achieve sub-millisecond responsiveness:
1. **Thin Client**: The `paneship render` command is a lightweight binary that merely sends your current context (CWD, exit code, width) to the daemon via a Unix socket.
2. **Persistent Daemon**: A background process (`paneship daemon`) maintains an in-memory cache and performs all rendering logic.
3. **Background Worker**: A dedicated thread in the daemon handles "heavy" tasks (like running `node -v` or `gix status`).
4. **Instant Response**: The daemon always returns the *best available* cached data immediately. If the data is stale (e.g., you just changed branches), it triggers a background refresh for the *next* prompt.
### Performance Optimizations
1. **Socket-Based Rendering** β The client does zero repository discovery or filesystem walking.
2. **Smart Invalidation** β The daemon monitors Git `HEAD` and shell exit codes to know when to refresh data.
3. **System Allocator** β Optimized for fast process startup times.
4. **Zero-Recursion** β Advanced process detection prevents redundant socket calls during background updates.
## Commands
### Rendering
```bash
# Render prompt with current context
paneship render
# Render with specific exit code
paneship render --exit-code 1
# Render for custom directory
paneship render --cwd /path/to/project
# Render with custom terminal width
paneship render --width 120
# Render with command duration
paneship render --duration-ms 2500
```
### Initialization
```bash
# Print shell initialization script for eval
paneship init zsh
# Append initialization to ~/.zshrc (interactive setup)
paneship init zsh --onboarding
```
### Daemon Management
```bash
# Start background daemon
paneship daemon
# Check if daemon is running
paneship daemon ping
```
### Benchmarking
```bash
# Run benchmark (150 iterations, 4 concurrent panes)
paneship benchmark --iterations 150 --panes 4
# Compare against Starship
paneship benchmark --iterations 150 --compare-starship
```
## Development
### Build
```bash
cargo build --release
```
### Test
```bash
cargo test
```
### Lint
```bash
cargo clippy --all-targets -- -D warnings
```
### Benchmark
```bash
cargo run --release -- benchmark --iterations 200 --panes 4
```
## Contributing
Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to get started, report bugs, and submit pull requests.
## Roadmap
Potential features and improvements:
- [ ] Bash and Fish shell support
- [ ] Windows terminal support (partial Rust support exists)
- [ ] Nix shell integration
- [ ] User-defined prompt modules via plugins
- [ ] Integration with system package managers for language detection
- [ ] VSCode integrated terminal support
- [ ] Performance profiling mode for debugging slow prompts
## Troubleshooting
### Prompt not updating
Check if the daemon is running:
```bash
paneship daemon ping
```
If it's not, manually start it:
```bash
paneship daemon > /dev/null 2>&1 &
```
### High CPU usage
- Verify Git repository health with `git fsck`
- Check if language detection is slow (profile with `paneship render --cwd <path>`)
- Increase cache TTL in `~/.config/paneship/config.toml` if working in large monorepos
### Incorrect directory display
Ensure `truncate_to_repo` is set appropriately in your config. If set to `true`, only the repository name and relative path are shown. Set to `false` to show your full home-relative path.
## Performance Comparison
On a mid-sized Rust repository (500+ dependencies):
| **Paneship (Daemon)** | **~1.5ms** |
| Paneship (Cold/No Daemon) | ~35ms |
| Starship | ~15ms |
| Oh My Zsh | ~150ms+ |
*Benchmarks run on a 2021 MacBook Pro; results vary by system and repository size.*
## License
Licensed under the MIT License. See [LICENSE](LICENSE) for details.
## Acknowledgments
- Built with [Gitoxide (gix)](https://github.com/Byron/gitoxide) for fast Git operations
- Unicode width handling via [unicode-width](https://crates.io/crates/unicode-width)
- Configuration via [TOML](https://crates.io/crates/toml)
- Serialization via [bincode](https://crates.io/crates/bincode)
## Support
For questions or discussions, feel free to:
- Open a [GitHub Discussion](https://github.com/andev0x/paneship/discussions)
- File an [issue](https://github.com/andev0x/paneship/issues)
- Check existing documentation and examples
---
**Paneship**: Fast, focused, productive. Happy coding!