🧭 Project Compass

Futuristic Project Navigator & Runner for the Modern Developer

Project Compass is a high-performance, TUI (Terminal User Interface) workspace orchestrator built with Ink and React. It transforms your terminal into a command center for managing complex, multi-stack environments with a focus on speed, safety, and visual clarity.

🛠️ Installation

``bash
npm install -g project-compass
`

🔗 Links

- NPM: npmjs.com/package/project-compass
- GitHub: github.com/CrimsonDevil333333/project-compass

!Navigator View

🌟 Premium Features

$3

- Automatic Discovery: Instantly scans and identifies Node.js, Python, Rust, Go, Java, Scala, PHP, and Ruby projects.
- Deep Detail View: Press Enter to reveal project manifests, detected frameworks, and available scripts.
- Custom Actions: Save persistent, project-specific commands with Shift+C (e.g., deploy|npm run deploy --prod).
- Live Output Panel: Stream real-time logs from active processes with dedicated scrolling (Shift+↑/↓).

$3

- Background Orchestration: Keep tasks running while you navigate the rest of your workspace.
- Process Management: Monitor status (Running, Finished, Failed, Killed) and forcefully terminate processes with Shift+K.
- Task Identity: Rename tasks on the fly with Shift+R to keep your workspace organized.
- Cross-Platform Safety: Automatically handles process signaling for both Unix (SIGKILL) and Windows (taskkill) to ensure clean exits.

!Task Manager

$3

- Context-Aware Management: Add or remove dependencies without leaving the app.
- Internal Switcher: Quick-swap projects within the registry view using S.
- Multi-Runtime Support: Handles npm, pip, and more based on project type.

!Package Registry

$3

- Rapid Scaffolding: Create new projects from scratch using industry-standard templates.
- Interactive Prompts: Safe, guided setup for directory structure and initial manifests.

!Project Architect

$3

- Environment Health (Shift+A): Audit your system dependencies and runtime versions.
- Build Atlas (Shift+B): A visual, art-coded representation of your project landscape.

!Omni-Studio
!Art Board

⌨️ Command Reference

| Shortcut | Action |
| :--- | :--- |
| ↑ / ↓ | Move project focus |
| Enter | Toggle project Detail View |
| Shift + T | Orbit: Task Manager |
| Shift + P | Registry: Package Manager |
| Shift + N | Architect: Project Creator |
| Shift + A | Studio: Environment Health |
| Shift + B | Toggle Art Board visibility |
| Shift + H | Toggle Help Cards |
| Shift + S | Toggle Structure Guide |
| Shift + Q | Quit (with safe-exit confirmation) |
| ? | Toggle Help Overlay |

$3

- Process Protection: Compass won't let you accidentally kill your work. If tasks are running, a dedicated confirmation dialog ensures you intended to quit.

!Exit Confirmation

⚙️ Configuration & Customization

Project Compass is designed to be personalized. All settings and custom commands are stored in a local JSON file.

- Linux/macOS: ~/.project-compass/config.json
- Windows: C:\Users\\.project-compass\config.json

$3


You can add your own project-specific commands directly within the app by pressing Shift+C in the Detail View. Use the format Label|Command (e.g., Deploy|npm run deploy).

$3

If you prefer manual editing, the config.json follows this structure:

`json
{
"showArtBoard": true,
"showHelpCards": false,
"showStructureGuide": false,
"customCommands": {
"/path/to/your/project": [
{
"label": "Build Production",
"command": ["npm", "run", "build", "--prod"]
}
]
}
}
`

- showArtBoard/HelpCards/Structure: Persistence for your UI visibility preferences.
- customCommands`: A map of absolute project paths to arrays of command objects.

---

🚀 Vision

Project Compass is designed to be the "Last Terminal Tool" you ever need to open. It bridges the gap between raw CLI commands and full IDEs, giving you a professional, reactive cockpit for all your development work.

---
Crafted with ❤️ by Satyaa & Clawdy
MIT License