Hostkeeper 🔐

Cross-platform SSH/SFTP management tool with secure credential storage

🚨 IMPORTANT: If you're an AI agent or joining this project mid-development, read PROJECT_STATE.md first for current status and handoff instructions.

---

📋 Project Status

Current Phase: Planning Complete → Ready for Implementation
Progress: 0% implementation, 100% planning
Estimated Timeline: 3-4 weeks to MVP

Quick Links

• 📊 PROJECT_STATE.md - START HERE - Current status & handoff guide
• 🏗️ Design Document - Architecture & technical decisions
• 📝 Implementation Plan - Detailed development tasks
• 📚 Documentation Index - All project documentation

---

✨ What is Hostkeeper?

Hostkeeper is a comprehensive SSH/SFTP management tool inspired by Termius, built with Go for maximum cross-platform compatibility.

Key Features

• 🔐 Secure credential management - Safe SSH key and password storage
• 📁 SFTP file operations - Built-in file transfer capabilities
• 🔑 SSH key management - Generate, import, organize keys
• 📤 Cross-device sync - Export/import credentials between devices
• 🖥️ Cross-platform - Linux, macOS, Windows, Termux (Android)
• 🎨 TUI interface - Interactive terminal user interface
• ⚡ Fast CLI - Quick commands for power users

---

🚀 Quick Start (For Users)

Note: This project is currently in early development. Not yet ready for production use.

Installation (when ready)

# From source
go install github.com/yourusername/hostkeeper/cmd/hostkeeper@latest

# Or build from source
git clone https://github.com/username/hostkeeper.git
cd hostkeeper
make build

Usage (planned)

# Add your first host
hostkeeper add

# List all hosts  
hostkeeper list

# Connect to host
hostkeeper connect myserver

# Launch TUI interface
hostkeeper tui

---

🛠️ Development

For Developers

👋 If you're joining development:

1. Read PROJECT_STATE.md first - This shows current progress
2. Check Implementation Plan - See what needs doing
3. Pick up next incomplete task and follow TDD approach

Getting Started

# Clone repository
git clone https://github.com/username/hostkeeper.git
cd hostkeeper

# Install dependencies  
go mod download

# Run tests
make test

# Build project
make build

# Run application
./build/hostkeeper --help

Tech Stack

• Language: Go 1.21+
• CLI Framework: Cobra
• TUI Framework: Bubble Tea
• SSH Library: golang.org/x/crypto/ssh

---

📚 Documentation Structure

docs/
├── plans/
│   ├── 2024-06-22-hostkeeper-design.md           # Architecture & design decisions
│   └── 2024-06-22-hostkeeper-implementation.md  # Step-by-step implementation guide
├── INSTALLATION.md                                # Installation guide (to be created)
├── USAGE.md                                      # User documentation (to be created)
└── ARCHITECTURE.md                                # Technical architecture (to be created)

Recommended Reading Order

1. PROJECT_STATE.md ⭐ Start here for current status
2. Design Document - Understanding the system
3. Implementation Plan - How to build it

---

🎯 Development Roadmap

MVP (Current Focus)

• ✅ Complete planning and design
• 🔲 Core SSH connection management
• 🔲 Host CRUD operations
• 🔲 Basic TUI interface
• 🔲 Export/import functionality
• 🔲 Cross-platform builds

Phase 2 (Enhanced Features)

• 🔳 Encrypted credential storage
• 🔳 SFTP TUI browser
• 🔳 SSH key generation
• 🔳 Connection snippets

Phase 3 (Advanced Features)

• 🔳 Cloud sync
• 🔳 Custom terminal emulator
• 🔳 Web interface
• 🔳 Plugin system

---

🤝 Contributing

For new contributors and AI agents:

1. Read PROJECT_STATE.md first to understand current progress
2. Check implementation plan for next tasks
3. Follow TDD approach (test → code → refactor)
4. Update PROJECT_STATE.md after completing work

Development Setup

See PROJECT_STATE.md for detailed development workflow and handoff procedures.

---

📊 Current Status

Component	Status
Planning & Design	✅ Complete
Implementation	🔲 Not Started
Testing	🔲 Not Started
Documentation	✅ Complete (technical docs)

Next Steps: Start implementation following the implementation plan

---

📞 Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

---

📄 License

MIT License - see LICENSE file for details

---

🙏 Acknowledgments

• Inspired by Termius
• Reference implementation: tamagosh
• Built with excellent open-source tools:
  • Cobra - CLI framework
  • Bubble Tea - TUI framework
  • golang.org/x/crypto/ssh - SSH library

---

📌 Remember: If you're continuing development work, always check PROJECT_STATE.md first to see what's been done and what needs to happen next!