A comprehensive Path of Exile desktop information tool inspired by PoE Overlay. Get real-time item pricing, character builds, atlas progression, and market data - all in one desktop application.
- Real-time Item Pricing - Instant valuations using PoE trade API
- Currency Exchange Rates - Live currency conversion and tracking
- Market Analysis - Advanced search and filtering tools
- Price History - Trends and market analysis
- Character Inspector - View builds, equipment, and stats
- Multi-Character Support - Switch between all your characters
- Skill Tree Viewer - Allocated passive points and build analysis
- Gear Analysis - Equipment optimization suggestions
- Atlas Completion Tracking - Monitor your atlas progress
- Map Bonus Overview - Track completion bonuses
- Atlas Passive Tree - View allocated atlas passives
- Progress Statistics - Detailed progression metrics
- Auto-Session Detection - Automatically detect PoE sessions from browser
- Direct API Access - No CORS limitations or proxy servers
- Offline Mode - Cached data when disconnected
- Native Performance - Fast, responsive desktop experience
- Download the latest release for your platform from Releases
- Install the application:
- Windows: Run the
.exeinstaller - macOS: Mount the
.dmgand drag to Applications - Linux: Install the
.AppImage,.deb, or.rpmpackage
- Windows: Run the
- Launch the app - PoE Toy Bocs will open in a 1778x1045 window
- Session Detection - The app will attempt to auto-detect your PoE session from browser cookies
- Optional Account Connection - Connect your PoE account for character data (OAuth)
- Select League - Choose your current league
- Start Exploring - Begin using item pricing and character tools!
- Node.js 18+
- npm or yarn
- Git
# Clone the repository
git clone https://github.com/Spiritbocs/poetoybocs.git
cd poetoybocs
# Install dependencies
npm install
# Start Next.js development server
npm run dev
# In another terminal, start the desktop app
npm run dev:electron# Build the Next.js app
npm run build
# Build desktop applications for all platforms
npm run electron:build
# Build for current platform only
npm run electron:distPoE Toy Bocs uses a dual authentication system for maximum functionality:
- POESESSID Cookie - Automatically detected from your browser
- Manual Entry - Copy session ID if auto-detection fails
- Purpose - Access trade API for item pricing and market data
- PoE Account Integration - Connect your official PoE account
- Purpose - Access character builds, atlas progression, passive trees
- Privacy - Only reads public character data, never modifies anything
- ✅ Basic desktop app structure
- ✅ OAuth authentication system
- ✅ Currency tracking functionality
- ✅ Item price checking (basic)
- 🔄 Desktop mode testing and validation
- 🔄 Enhanced session detection
- 📋 Character data integration
- 📋 Atlas progression tracking
- 📋 Enhanced item evaluation tools
- 📋 Performance optimization
See our Development Plan and Kanban Board for detailed roadmap.
We welcome contributions! Here's how you can help:
Use our Bug Report Template to report issues.
Use our Feature Request Template to suggest new features.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
We use a kanban board to track development. Check our GitHub Projects to see current work and pick up tasks.
- Framework: Next.js 14 + Electron
- Language: TypeScript
- UI: React + Tailwind CSS
- APIs: PoE Official API (OAuth + Trade)
- Desktop: Electron with secure IPC
- Build: electron-builder for cross-platform
├── electron-main.js # Main Electron process
├── electron-preload.js # Secure IPC bridge
├── app/ # Next.js application
├── components/ # React components
├── lib/ # Utilities and API clients
└── .github/ # CI/CD and project templates
This project is licensed under the MIT License - see the LICENSE file for details.
- Path of Exile - Amazing game by Grinding Gear Games
- PoE Overlay - Inspiration for desktop tool design
- Awakened PoE Trade - Session management approach
- PoE Community - Feedback and feature suggestions
- Issues: GitHub Issues
- Releases: GitHub Releases
- Project Board: GitHub Projects
- PoE API: Official PoE API
Made with ❤️ for the Path of Exile community
- Realm + League aware pricing (PC / Xbox / PlayStation)
- Single league dropdown (current + previous) sourced live from official PoE API (
/leagueendpoint) - Currency exchange (Chaos ⇄ Divine reference, buy/sell style rows)
- Item overview tables for many poe.ninja categories (maps, uniques, fossils, essences, etc.)
- Dynamic representative sidebar icons fetched once per (realm, league)
- Auto‑filtering & search within item tables
- Low‑confidence filtering safeguards (avoids empty tables)
- Theme‑styled scrollbar & enlarged high‑visibility icons
- Persistent realm + league selection (localStorage)
- 10‑minute in‑memory caching of upstream calls to reduce load
app/ # Next.js App Router entry
api/ # Internal proxy endpoints (ninja + leagues + oauth)
oauth/ # OAuth callback UI
page.tsx # Main layout + state orchestration
components/ # UI components (selectors, tables, sidebar, auth status)
lib/ # API abstraction (poe-api.ts)
public/ # Static assets / placeholder images
styles/ # Global and theme CSS
The current implementation includes a client id & secret in poe-api.ts (to be moved server‑side before making the repo public). For local development you must register a matching redirect URI (e.g. http://localhost:3000/oauth/callback) or use the production Vercel URL.
Recommended next hardening steps (NOT yet implemented):
- Move OAuth config to environment variables (
NEXT_PUBLIC_POE_CLIENT_ID, backend secret only for token exchange route). - Remove the client secret from any code that runs in the browser (PKCE suffices).
- Separate dev & prod app registrations.
pnpm install # or npm install / yarn install
pnpm dev # start Next.js on http://localhost:3000Open the site, pick Realm + League; selections persist until storage cleared.
| Source | Purpose | Internal Proxy |
|---|---|---|
Official PoE API /league |
Live league list (current & previous) | app/api/poe/leagues |
poe.ninja currencyoverview |
Currency & fragment prices | app/api/ninja/currency |
poe.ninja itemoverview |
Item category prices | app/api/ninja/items |
- Client in‑memory map (10 min TTL) inside
poe-api.tskeyed by:currency-${realm}-${league}-${type}&itemOverview-${realm}-${league}-${type}. - Server proxy mini caches (2–5 min) to shield poe.ninja & PoE endpoints.
| Variable | Description |
|---|---|
| NEXT_PUBLIC_POE_CLIENT_ID | OAuth client id (public) |
| POE_CLIENT_SECRET | Server‑side secret used only by token route |
| NEXT_PUBLIC_REDIRECT_URI | OAuth redirect (matches registration) |
Item categories map via sectionToItemType (in app/page.tsx) & mapKeyToType (in sidebar-nav.tsx). Add the key + poe.ninja type and the UI will fetch automatically.
- Increase / decrease icon sizes centrally in component styles.
- Adjust cache TTL in
lib/poe-api.ts(cacheTimeout). - To force refresh: clear site storage (DevTools > Application > Clear storage) or restart dev server.
- Load site; verify league dropdown lists current & previous leagues.
- Switch realm; ensure list reloads & selection persists across reloads.
- Choose categories in sidebar; tables populate with icons & prices.
- Hard reload; previous league + realm restored.
Currently PRIVATE. License to be chosen before making repository public.
- Move OAuth credentials to env
- Manual refresh button / stale indicator
- Split cache TTL per data type
- Error badges for empty categories
- Basic automated tests
If you publish the repository later, scrub secrets and finalize a license first.