Paprwork V2
AI-Powered Desktop Assistant — Rebuilt with TypeScript and Mastra
Features • Quick Start • Architecture • Documentation • Contributing
✨ Features
- 🤖 Multi-Provider AI Support - Claude, GPT, and Gemini models with seamless switching
- ⚡ Streaming Responses - Real-time AI responses with proper tool execution
- 🛠️ Extensible Tool System - Bash execution, filesystem operations, document processing
- 📋 Parallel Chat Sessions - Multiple concurrent AI conversations
- ⏱️ Scheduled Jobs & Automation - Python/Node/Swift jobs with cron scheduling
- 🧠 Smart Memory System - Context-aware conversations with Papr Memory integration
- 🎨 Mini-Apps - TypeScript apps with SQLite database access
- 👥 Sub-Agents - Specialized AI agents for research, code review, and more
- 🔐 Secure Custom Keys - Manage your own API keys with encrypted storage
- 💻 Cross-Platform - macOS, Windows, and Linux support
🚀 Quick Start
For End Users (Recommended)
Download the packaged app - no prerequisites needed!
-
Download the latest release from GitHub Releases
- macOS: Download
.pkg (recommended — installs to Applications and opens the app) or .zip (manual: unzip → drag to Applications)
- Windows: Download
.exe installer
- Linux: Download
.AppImage or .deb
-
Install and run — the Mac PKG and Windows installer can launch the app when setup finishes. Everything is included.
-
Optional: Sign in with Papr for automatic API key provisioning
No Node.js, npm, or technical setup required. See User Installation Guide for details.
For Developers (Running from Source)
Prerequisites:
- Node.js v24+ (required for Electron 40)
- npm v10+
- macOS, Windows, or Linux
Installation:
# 1. Clone the repository
git clone https://github.com/Papr-ai/paprwork.git
cd paprwork
# 2. Use Node v24+ (with nvm)
nvm use 24
# 3. Install all dependencies (includes UI workspace)
npm install
# 4. Configure API keys
cp .env.example .env.local
# Edit .env.local and add your API keys
# 5. Start the application
npm start
Note: This project uses npm workspaces. Running npm install at the root automatically installs dependencies for both the main app and the ui/ workspace. You don't need to run npm install separately in the ui/ folder.
Troubleshooting:
- If you get "cannot find module" errors during build, delete
node_modules and ui/node_modules, then run npm install again
- Make sure you're using Node v24+ (
node -v should show v24.x.x)
Development Mode
# Run in development mode with hot reload
npm run dev
# In separate terminals:
npm run gateway:dev # Gateway process
npm run ui:dev # UI with Vite HMR
npm run electron:dev # Electron app
🏗️ Architecture
Paprwork V2 is built with a modern, modular architecture inspired by OpenClaw (179k+ stars):
paprwork-v2/
├── src/
│ ├── core/ # Shared library (zero duplication!)
│ │ ├── agents/ # MastraAgent, SessionManager
│ │ ├── tools/ # Tool implementations
│ │ └── types/ # Type definitions
│ ├── electron/ # Main Electron process (CommonJS)
│ ├── gateway/ # Gateway process for sub-agents & jobs
│ └── resources/ # Agent docs, skills, templates
├── ui/ # React UI (Vite + TypeScript)
├── docs/ # Documentation
└── tests/ # Comprehensive test suite
Key Design Principles
- 100% TypeScript - Full type safety, zero
any types
- Small, Modular Files - Max 500 lines per file (enforced by CI)
- Shared Core Library - Zero code duplication between processes
- Mastra Framework - Reliable multi-provider AI orchestration
- Rust-Based Tools -
oxlint and oxfmt for 50-100x faster dev workflow
Optional usage telemetry
The desktop app can send anonymous, coarse usage events (for example app started or quit) to help measure adoption. This follows the same proxy pattern as Papr Memory OSS: the app never embeds an Amplitude API key; events are POSTed to https://memory.papr.ai/v1/telemetry/events, and the server forwards to Amplitude.
- Default: On for packaged installs (Mac/Windows/Linux downloads from releases). Off when running from source/dev (
electron unpackaged). Change anytime under Settings → Privacy. PAPRWORK_TELEMETRY_ENABLED=true|false still overrides the stored preference.
- Disable: Turn off in Settings → Privacy, or set
PAPRWORK_TELEMETRY_ENABLED=false (forces off regardless of package default).
- Custom endpoint: Set
PAPRWORK_TELEMETRY_URL to your own proxy base URL (must be http:// or https://). Set PAPRWORK_TELEMETRY_URL= (empty) to block all telemetry network calls.
- Not collected: Chat content, prompts, file paths, API keys, or personal data. Implementation:
src/core/telemetry/.
- Operational signals (gateway): When telemetry is on, the jobs gateway may emit coarse diagnostics (for example
paprwork_job_failed, paprwork_scheduler_cron_parse_error, throttled paprwork_scheduler_tick) with no stack traces and no stderr. This helps spot patterns in Amplitude; it is not a full crash/bug reporter. For deep production error tracking, add something like Sentry separately.
📚 Documentation
Quick Links
🛠️ Development
Code Quality
# Run all checks (type-check + format + lint + LOC)
npm run check
# Format code with oxfmt (Rust, 30x faster)
npm run format
# Lint with oxlint (Rust, 50-100x faster)
npm run lint
# Type checking (TypeScript)
npm run type-check
Testing
# Run all tests
npm run test
# Unit tests (backend)
npm run test:unit
# Unit tests (UI)
npm run test:ui
# Integration tests
npm run test:integration
# E2E tests
npm run test:e2e
# Watch mode
npm run test:watch
Building
# Build all components
npm run build
# Build individual components
npm run build:gateway
npm run build:electron
npm run build:ui
# Package for distribution
npm run package
🌟 Why V2?
Paprwork V1 accumulated technical debt over time:
- 30,335 lines in monolithic files
- 90% code duplication between processes
- Fragile with 10+ patches for tool calling
- No type safety, tight coupling
V2 is a complete greenfield rewrite focused on:
- ✅ Production-ready architecture
- ✅ Comprehensive test coverage
- ✅ Modern tooling (Rust-based linters/formatters)
- ✅ Type safety throughout
- ✅ Modular, maintainable codebase
🤝 Contributing
We welcome contributions! Please see our Contributing Guidelines for details.
Quick Contribution Checklist
📄 License
GNU Affero General Public License v3.0 - see LICENSE for details.
🙏 Acknowledgments
📞 Support
Built with ❤️ using TypeScript, Electron, and Mastra
⬆ Back to Top
