🍌 Peely

Your Personal AI Assistant in the Terminal

A lightweight, extensible command-line AI assistant powered by GitHub Copilot

Features • Quick Start • Usage • Daemon Mode • Documentation

🌟 Features

• 🚀 Fast & Lightweight — Quick AI queries right from your terminal
• 🔌 Extensible Plugin System — Custom tools, timers, and integrations
• 💬 Multiple Interfaces — Terminal TUI, Discord bot, or CLI commands
• ⚡ Daemon Mode — Persistent background operation with shared state
• 🎯 GitHub Copilot Support — Leverage GitHub Copilot's AI capabilities

🎯 Why Peely?

Peely brings AI assistance directly to your command line with a focus on speed, flexibility, and ease of use. Whether you need quick answers, want to run a Discord bot, or need a persistent AI assistant running in the background, Peely has you covered.

📋 Prerequisites

• Node.js (LTS version 14 or higher)
• npm (bundled with Node.js)
• GitHub Copilot subscription (for AI features)

⚠️ Important Security Note

Versions prior to 0.9.4 are vulnerable to a critical security issue. Please update to the latest version immediately.

🚀 Quick Start

Installation

# Clone the repository
git clone https://github.com/real-kijmoshi/peely.git
cd peely

# Install dependencies
npm install

# Start interactive mode
npm start

Alternatively, install the published package from npm:

# Install globally to use the `peely` CLI
npm install -g peely

# Or install locally in a project
npm install peely

# Run installed CLI
peely

First-Time Setup

# Run the setup wizard
npx peely setup

# Configure your AI model
npx peely model

# Start using Peely!
npx peely chat "Hello, Peely!"

💡 Usage

Interactive Terminal UI

Launch the interactive TUI for a conversation-style experience:

npm start
# or
npx peely

Available Commands:

• /help — Show available commands
• /clear — Clear conversation history
• /status — Show configuration status
• /pair discord <code> — Pair your Discord account
• /exit or /quit — Exit the application

One-Shot Commands

Quick AI queries without entering interactive mode:

# Ask a question
npx peely chat "What's the weather like?"

# Get help
npx peely help

# Check status
npx peely status

Discord Bot

Run Peely as a Discord bot:

# Set up Discord bot token
npx peely pair discord setup

# Start Discord bot
npx peely discord

⚡ Daemon Mode

Recommended for the best experience!

The daemon runs Peely in the background, providing persistent operation, faster responses, and shared state across all interfaces.

🎬 Starting the Daemon

npx peely daemon start
# or
npm run daemon:start

The daemon will:

• ✅ Start the Discord bot (if configured)
• ✅ Handle plugin events and timers
• ✅ Accept connections from CLI clients
• ✅ Maintain conversation history
• ✅ Run in the background until stopped

📡 Using the Daemon

Once running, all CLI commands automatically connect to the daemon:

# Chat (connects to daemon automatically)
npx peely chat "Explain quantum computing"

# Check daemon status
npx peely daemon status

# Restart daemon (useful after updates)
npx peely daemon restart

# Stop daemon
npx peely daemon stop

🔄 Updating Peely

When you update Peely, simply restart the daemon to reload all code:

git pull
npx peely daemon restart

No configuration loss! Your conversation history and settings are preserved.

🏗️ Architecture

The daemon architecture provides several benefits:

| Legacy Mode | Daemon Mode ✨ | |----------------|-------------------| | Separate processes for each interface | Single persistent process | | No shared state | Shared conversation history | | Manual restarts required | Hot reload with daemon restart | | Slower startup | Instant CLI responses |

For detailed architecture information, see DAEMON.md.

📚 Documentation

• DAEMON.md — Detailed daemon architecture and IPC protocol
• GitHub Copilot Setup — Guide to using GitHub Copilot API

🛠️ Development

Project Structure

peely/
├── cli.js              # Main CLI entry point
├── src/
│   ├── ai/             # AI provider integrations
│   ├── daemon/         # Daemon server and client
│   ├── interfaces/     # Terminal and Discord interfaces
│   ├── plugins/        # Plugin system
│   └── utils/          # Utilities and configuration
├── data/               # Persistent data storage

Running Tests

npm test

Configuration

Configuration is stored in config.json. You can modify settings using CLI commands or by editing the file directly.

🐛 Troubleshooting

Getting Help

• 📖 Check the documentation
• 🐛 Open an issue
• 💬 Join the discussions

🤝 Contributing

Contributions are welcome! Here are some ways you can help:

• 🐛 Report bugs and issues
• 💡 Suggest new features or improvements
• 📝 Improve documentation
• 🔧 Submit pull requests

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

👤 Author

real-kijmoshi

• GitHub: @real-kijmoshi

⬆ Back to Top

Made with ❤️ by the Peely team