README.md

June 2, 2026 · View on GitHub

GA Manager

GA Manager

Multi-instance GenericAgent Desktop Manager
Create, monitor, and orchestrate AI agent instances with a modern desktop UI.

中文文档 • Quick Start • Features • Usage Guide • Build

Quick Start

  1. Download from Releases
  2. Install:
    • Windows: Run GA-Manager-X.X.X-x64.exe — one-click silent install
    • macOS: Open .dmg, drag to Applications. First launch: right-click → "Open"
    • Linux: chmod +x GA-Manager-*.AppImage && ./GA-Manager-*.AppImage
  3. First-run Setup Wizard will guide you to configure GA Root path
  4. Click "Validate" to verify your environment, then "Get Started"

Prerequisites:

  • GenericAgent installed
  • Python 3.10+ (python or python3 in PATH, or configure full path)
  • Configured mykey.py in your GenericAgent directory

Features

FeatureDescription
ChatReal-time conversation with Agent, markdown rendering, image paste, session history
ConductorMulti-agent orchestration — create subagents, coordinate complex tasks
HiveGoal-based multi-agent collaboration via BBS message board
MorphlingProject capability absorption/replacement via Hive
MonitorToken cost tracking, system resources (CPU/Memory)
SkillsSkill tree visualization + SOP file editor
TODO WidgetFloating task list — manual add, auto-detect from Agent replies, execute via Agent/Hive
RewindTime-travel through conversation history, fork branches, switch between timelines
Desktop PetAnimated pixel pet that roams the screen with DyberPet-style frame animations
Sakura ThemeGlassmorphism UI with transparent window, subtle pink accent, customizable opacity
Auto UpdateAutomatic update detection, download, and silent install

Usage Guide

1. Setup & Configuration

On first launch, the Setup Wizard appears:

  • GA Root: Path to your GenericAgent directory (contains agentmain.py)
  • Python Path (optional): Leave empty for auto-detection, or specify full path
  • Click Validate to check: GA path ✓, Python ✓, Bridge ✓
  • Click Get Started to save

To reconfigure later: Settings → Reconfigure button

2. Creating Instances

  1. Click + New in the sidebar
  2. Enter instance name (optional, auto-generated if empty)
  3. GA Root auto-fills from your configuration
  4. Select LLM model (reads from your mykey.py)
  5. Click Create — instance starts automatically

3. Chat

  • Type messages in the input area, press Enter or click Send
  • Image paste: Ctrl+V to paste screenshots directly
  • Session history: Click any session in the sidebar to restore
  • Double-click a session to rename it
  • Search: Use the search box in History section
  • Review: Click "Review" button to run code review on uncommitted changes

4. Feature Toggles (Sidebar)

Click to enable/disable for the active instance:

ToggleWhat it does
AutonomousAgent works independently after 30min idle
ReflectSelf-check after each action, maintains direction
SchedulerCron-based scheduled task execution
Dev ModeInjects development best practices into system prompt

5. Conductor (Multi-Agent Orchestration)

What: Create multiple sub-agents working in parallel, coordinated by a conductor.

How to use:

  1. Go to Conductor page
  2. Click Start Conductor (auto-installs dependencies if needed)
  3. Type a task in the chat panel (right side)
  4. Conductor analyzes and dispatches to sub-agents
  5. Click any sub-agent card to view its full output
  6. Continue chatting to refine or assign new tasks

Best for: Complex tasks that can be split into parallel subtasks (e.g., "Design a REST API with docs, tests, and deployment config")

Port: Auto-detects available port (default 8900, falls back if occupied)

6. Hive (Goal Collaboration)

What: Multiple Agent workers collaborate via a shared BBS message board toward a common goal.

How to use:

  1. Go to Hive page
  2. Enter your objective (e.g., "Research and summarize top 5 AI frameworks")
  3. Set time budget (minutes) and number of workers
  4. Click Start Hive
  5. Watch the message stream as workers coordinate
  6. Send additional instructions via the message input

Best for: Research tasks, information gathering, tasks requiring multiple perspectives

Requirements: pip install fastapi uvicorn python-multipart (auto-installed on first use)

7. Morphling (Project Absorption)

What: Structured workflow for absorbing or replacing external project capabilities. Uses Hive for parallel execution.

How to use:

  1. Go to Morph page
  2. Enter target project (GitHub URL, product name, or description)
  3. Select mode:
    • Call: Integrate target into your toolchain
    • Rewrite: Understand core, implement better version from scratch
    • Hybrid: Call some components, rewrite others, discard the rest
  4. Optionally fill in test criteria and known components
  5. Set time budget and worker count
  6. Click Start Morphling — launches Hive with structured objective

Best for: Analyzing competitor projects, absorbing open-source capabilities, building replacements

8. Rewind (Time Travel)

What: Navigate through conversation history like a timeline. Fork at any point to explore alternative paths.

How to use:

  1. Click Rewind in the chat toolbar
  2. Use the slider to browse any point in the conversation
  3. Messages after the current point are dimmed
  4. Click ◀ ▶ for step-by-step navigation, Latest to jump to present
  5. Click Fork to branch from the current point:
    • Original conversation is saved as a branch
    • You continue from the fork point with a clean slate
  6. Use Branches (N) dropdown to switch between saved branches
  7. Hover over branch options to preview their content

9. TODO Widget

A floating task card that stays visible on all pages:

  • Drag the title bar to move it anywhere
  • Click title to collapse/expand
  • Add tasks: Type in the input box, press Enter
  • Complete: Check the checkbox
  • Delete: Hover and click ×
  • Auto-detect: When Agent replies contain "TODO:", "待办:", "需要:" etc., suggestions appear
  • Auto-complete: When Agent reports a task as done, it's automatically checked off
  • Execute all: Click ▶ button to choose execution mode:
    • Send to Agent — sends task list to current chat
    • Auto Execute — Agent works autonomously
    • Hive Mode — starts Hive with tasks as objective
  • Archive: Click "Archive Done" to let Agent summarize completed tasks

Persistence: Tasks saved to backend (~/.ga-manager/todos.json), survives restarts

10. Monitor

  • Cost Tracking: Requests, Input/Output tokens, Cache hit rate, Duration, Total
  • System Resources: CPU and Memory usage bars
  • Data refreshes every 5 seconds

11. Skills & SOP

  • Left panel: Browse SOP files from GA's memory/ directory
  • Right panel: View/edit SOP content, or view the Skill Tree visualization
  • Create: Click "+ New" to create a new SOP file

12. Settings

  • Theme: Dark / Light (Sakura Bloom glassmorphism style)
  • Window Opacity: Slider to adjust transparency (50%-100%)
  • Language: English / Chinese
  • App Config: GA Root, Python path, Port, Pets Directory
  • mykey.py Editor: Edit LLM API keys directly
  • Check Updates: Manual update check
  • Reconfigure: Re-enter Setup Wizard

13. Desktop Pet

Animated pixel pet that lives on your screen, inspired by DyberPet.

Behaviors:

  • Idle: Loops default animation
  • Walk: Randomly walks left/right across the screen
  • Sleep: Occasional sleep animation
  • Click: Dialogue bubble + patpat reaction animation
  • Drag: Drag animation, fall on release
  • Working: Special animation when Agent is busy

Pet Selection: Right-click the pet to open the character selector (13+ bundled pets).

Custom Pets: Place DyberPet-compatible character folders in Settings → Pets Directory:

YourPetsDir/
└── 角色名/
    ├── act_conf.json    (action configuration)
    └── action/          (PNG frame sequences)
        ├── stand_0.png
        ├── stand_1.png
        ├── walk_0.png
        └── ...

Desktop Mode (Electron): Pet runs in an independent transparent window — drag it anywhere on screen, not confined to the app window.

14. Auto Update

  • App checks for updates on startup (after 15s) and every hour
  • When a new version is found, a notification appears at bottom-right
  • Click Download to start downloading
  • When ready, click Restart Now to install immediately
  • Or click Install on Quit for silent install on next exit

Build from Source

Prerequisites

  • Go 1.21+
  • Node.js 18+ & npm
  • Python 3.10+

Build

git clone https://github.com/chilishark27/ga-manager.git
cd ga-manager

# Frontend
cd frontend && npm install && npm run build && cd ..

# Backend (choose your platform)
cd backend
GOOS=windows GOARCH=amd64 CGO_ENABLED=0 go build -o ../build/windows-amd64/ga-manager.exe .
GOOS=darwin GOARCH=arm64 CGO_ENABLED=0 go build -o ../build/darwin-arm64/ga-manager .
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -o ../build/linux-amd64/ga-manager .
cd ..

# Electron (on target platform)
cd electron && npm install
npm run build:win    # Windows
npm run build:mac    # macOS
npm run build:linux  # Linux

Run without Electron (development)

cp -r frontend/dist backend/static
cd backend && go run . --no-gui
# Open http://localhost:18600

Architecture

┌─────────────────────────────────────────────┐
│  Electron (Desktop Shell)                   │
│  - Main Window (transparent, frameless)     │
│  - Pet Window (always-on-top, independent)  │
│  - Auto-update (electron-updater)           │
│  - System tray, folder picker               │
├─────────────────────────────────────────────┤
│  Go Backend (port 18600)                    │
│  - REST API + WebSocket                     │
│  - Instance lifecycle management            │
│  - Pet discovery API (/api/pets)            │
│  - Conductor/Hive process management        │
│  - Cost persistence (~/.ga-manager/)        │
├─────────────────────────────────────────────┤
│  bridge.py (stdin/stdout JSON protocol)     │
│  - Spawns GenericAgent per instance         │
│  - Feature toggles, cost tracking           │
├─────────────────────────────────────────────┤
│  GenericAgent (Python) × N instances        │
│  - LLM interaction, tool execution          │
│  - Self-evolving skill tree (SOPs)          │
│  - Hierarchical memory                      │
├─────────────────────────────────────────────┤
│  Conductor (FastAPI, dynamic port)          │
│  Hive BBS (FastAPI, random port 58800+)     │
└─────────────────────────────────────────────┘

Credits

  • GenericAgent — the AI agent framework
  • DyberPet — desktop pet animation assets
  • Built with Go, React, TypeScript, Electron