Documentation

Everything about BagIdea Office — what it is, every feature, how to install, and the full CLI.

Introduction

BagIdea Office is a living AI-agent office that runs as your desktop wallpaper. Every AI agent on your machine becomes a pixel-art employee in an HD-2D office: they walk to their desks when real work starts, gather at Security to ask permission, hold meetings, learn skills, and the lights follow your real local time.

It is not a dashboard and not a chat window — it is a world that renders the true state of your Claude Code sessions, headless agent runs and custom scripts as living characters, behind your desktop icons.

Three independent layers keep it robust: a zero-dependency Node daemon (the source of truth), a Godot 4 renderer (the wallpaper), and a lightweight overlay UI (chat, settings, approvals). The daemon keeps agents running even if rendering restarts.

📚 Full guides — how to use every feature

This page is the overview. For step-by-step how-to on every feature — hiring agents, projects, channels, web automation, voice, plugins, models and more — open the full guides (they render on GitHub):

Browse all guides on GitHub ↗

What it is

At its heart, BagIdea Office is an operations layer for AI agents — given a place. Instead of a flat list of tasks, you get a spatial, honest view of what your agents are actually doing:

• Real Claude Code sessions, spawned with each agent's persona, skills and allowed tools.
• A CEO → Director → team chain of command you drive by giving orders.
• Spatialized permission approvals — agents walk to Security for tools you haven't granted.
• Real project folders, resumable sessions, and self-splitting sub-agents for parallel work.

Core concepts

You are the CEO

The gold seat is you. Type an order and the Director (the main Claude agent) walks over, takes it, plans, and delegates to the team.

The Director

main is Claude itself — the office manager who answers you, creates projects, and routes work with DELEGATE lines.

Ghosts (sub-agents)

When a job parallelizes, an agent splits into translucent clones that work on the Ghost Deck and merge back with a synthesis.

The room grid

The floor is a 3×3 jigsaw of identical rooms; any room fits any slot, so you can rearrange the whole office in the editor.

Installation

Quickest — one line, any OS

With Node installed, this sets up the office for your platform — it downloads a prebuilt app, so there's no Visual Studio Build Tools or Rust to compile.

npx bagidea

Windows — one-shot installer (recommended)

Open PowerShell and run the command below. It installs every dependency (Git, Node LTS, Rust, Godot 4.6.3, Claude Code CLI), clones the app to %LOCALAPPDATA%\BagIdeaOffice, builds the desktop shell, brands the window icon, adds bagidea to your PATH, and creates a Start Menu shortcut. It is safe to re-run — each step skips what's already done.

irm https://raw.githubusercontent.com/bagidea/bagidea-office/main/installer/install.ps1 | iex

macOS — one-shot installer (beta)

Open Terminal and run the command below. It installs the dependencies (Git, Node, Rust, Godot, Claude Code CLI), clones the app to ~/BagIdeaOffice, builds the desktop shell and the wallpaper-embed shim, wires the Claude hooks, and sets up the bagidea command. Safe to re-run.

curl -fsSL https://raw.githubusercontent.com/bagidea/bagidea-office/main/installer/install-mac.sh | bash

Linux — one-shot installer (experimental 🧪)

Ubuntu/Debian (apt) for now. Open a terminal and run the command below. It installs the dependencies (Node 20, Rust, Git, WebKitGTK, GTK, wmctrl/xdotool, PulseAudio utils, Godot 4.6.3), builds the desktop shell, wires the Claude hooks, symlinks bagidea into ~/.local/bin, and adds an XDG autostart entry. On X11/Xorg the office attaches as the real desktop wallpaper; on Wayland it falls back to a fullscreen window pinned below everything. Please report problems with your distro, desktop, and the output of "echo $XDG_SESSION_TYPE".

curl -fsSL https://raw.githubusercontent.com/bagidea/bagidea-office/main/installer/install-linux.sh | bash

Manual build

Clone the repository, point the Claude hook paths at your clone, then build the Rust shell:

git clone https://github.com/bagidea/bagidea-office.git
cd bagidea-office\shell
cargo build --release   # → shell/target/release/bagidea-office-shell.exe

First run

Log in to Claude once, then start the office. Your wallpaper becomes the live office; a chat head and tray icon appear.

claude          # sign in (first time only)
bagidea start   # launch the office

If the install fails

The installer is built to finish on a bare machine, but here are the common snags and their fixes. Almost all are solved by opening a NEW terminal and re-running the installer — re-runs are safe and keep your data.

Using it

Chat & the CEO

The chat panel opens on your CEO seat. Type an order in the CEO seat and the Director walks over to take it, plans, and delegates — you watch the hand-offs on the wallpaper, and the summary is walked back to you. To talk to any agent directly, click their face in the rail or on the live map. Every conversation is a resumable thread with full history.

Projects

Register real folders as projects (with PLACE shorthands like "classroom → D:\Learning"). The Director can create new projects himself and route work into them; the assignee's Claude session runs inside that directory and is resumable. One occupant at a time: while an agent works a project you can't open it (a ⏹ stop-agent button with a two-click confirm lets you take over), and while you have it open an agent won't enter.

The whole roster arranges itself into an org chart (🗂 → ORG): CEO → Director → mid → staff. Hire from ⚙ → AGENTS: name, role, avatar + aura, tier, a Persona Copilot that fills the prompt and picks fitting skills + tools, one of 16 voices, and the exact tools each agent may run.

Permissions

Tools you grant in an agent's profile run silently — and the agent never even leaves its desk. For anything else, the agent walks to the Security Center and waits while a card pops up with the exact command. Choose Allow, ✓✓ Forever (remembers the grant), or Deny. No answer in 50 seconds auto-denies and the agent re-plans.

The 3D Editor

Open the editor (the 🎨 button or bagidea editor) to rearrange the office in true 3D: click two rooms to swap them on the 3×3 grid, move the Ghost Deck, place furniture and decor, and import your own .glb/.gltf/.fbx models and images. Save and the wallpaper updates instantly — furniture, agent seats, navigation and pets all follow.

Voice & channels

Hold F6 anywhere to speak a command to the office. Give agents one of 16 TTS voices (split clearly ♀/♂). Call the main agent for a realtime voice conversation (Gemini Live) in its assigned voice. Connect Telegram, Discord or LINE and command your office from your phone — replies come back on the same channel.

Updates & start-up

A VERSION file marks real releases: the office only shows the 🔄 update banner when main's version is newer than yours, so routine commits never nag you. Click the banner or run bagidea update to pull, rebuild and relaunch (your data is kept). Set it to launch with Windows from the tray, settings, or bagidea startup on.

Swappable brains (any model)

Run each agent on its own model. Claude Code stays the engine — only the brain behind it swaps, and it fails open to Claude, so nothing changes until you opt an agent in. No LiteLLM or Python to install — a translation proxy is built into the daemon.

• Direct (Anthropic-compatible): Claude · GLM (Z.AI) · DeepSeek · Qwen (Alibaba) · MiniMax · Kimi (Moonshot)
• Via the built-in proxy (OpenAI-compatible): OpenAI · Gemini · OpenRouter · NVIDIA · Groq · Cerebras · xAI (Grok) · Mistral · Together · Fireworks — plus local Ollama / LM Studio with no API key. Pickers fetch each provider's live model list.
• Custom providers: add your own — name + Base URL + key, Anthropic- or OpenAI-style (point it at a LiteLLM gateway if you run one).

Set it up: ⚙ CONNECT → 🧠 MODELS/PROVIDERS → paste a key → Connect (✅). Then ✏️ edit an agent → 🧠 Brain → pick provider + model (a working default is auto-selected) → Save.

Free to try, with limits: NVIDIA build is free but rate-limited (~40 req/min); OpenRouter has free :free models that are daily-capped (use vendor/model ids); Gemini has a generous free quota; OpenAI Tier 1 (30k tokens/min) is small for heavy agent work.

Auto-compact + auto-new-thread — for every model. Long chats never clog: before each turn the office measures the thread against the model's context window and, if it's filling up, summarizes it with Claude and continues on a fresh thread — recovering the same way if a backend rejects a too-big request. Continuity is preserved (the summary is Claude-written) and the view follows you to the new thread.

Monitor it: every message is tagged with its model, the thread bar shows a live context meter (e.g. gpt-4o · 40k/128k), the 🧠 BRAINS panel tracks every provider + agent, and STATS estimates per-provider spend.

Plugins, skills & tools

Plugins extend the office for real — a folder with a manifest can add UI panels, HTTP routes, and commands agents can drive, with ctx access to the registry, feed, broadcasting and even running Claude turns. Two core plugins ship in the box (🎵 Music Player, 🧮 Calculator); install more from any GitHub repo. Start from the official template, or read the worked example repos.

bagidea plugin install https://github.com/bagidea/bagidea-office-template

Every office ships with a library of builtin skills (deep research, office control, plugin building, code review, docs, debugging, data wrangling, project kickoff, diagrams) you can assign to any agent, plus Hermes-style skills the office learns automatically after real work. Add new raw capability via MCP servers.

Workflow Builder

Plan work as plain-language nodes on a drag-drop canvas (⋯ menu → Workflow Builder) — each node is a step (trigger / fetch / action / decision / output) and the flow reads top to bottom. Press Analyze and the Director reads your plan and tells you which skills and tools it needs, what permissions or extra agents to add, and what's still undecided — so you can plan work even if you don't know how to instruct it, and let the team work out the execution.

1. Add nodes & write in plain language. e.g. “every morning summarize AI news, then send it to Telegram”. Drag cards to order the flow top→bottom.
2. Analyze. The Director returns a plan: needed skills/tools, permissions/agents to set up, and open questions. (This release plans only — it doesn't auto-run yet.)
3. Save & reuse. Workflows are stored under workspace/workflows. Three example workflows ship in the box to learn from.

Languages

The whole interface supports 14 languages. English is the default; pick another in settings and the office translates office-wide (and remembers your choice per machine). This website speaks the same 14 languages — use the picker in the top bar.

en ไทย 中文 Español हिन्दी العربية Português Русский 日本語 Deutsch Français 한국어 Indonesia Tiếng Việt

Sponsoring

BagIdea Office is free and open source; sponsorship funds development, art licenses and cross-platform backends. It is a recurring monthly subscription run entirely by GitHub Sponsors (like a YouTube or Patreon membership) — secure payments, tax and payouts are GitHub's job, not ours. Four monthly tiers: 💛 Supporter ($5), 🥉 Bronze / Backer ($30), 🥈 Silver Partner ($300), 👑 Gold Partner ($3,000).

1. Choose a tier & sponsor. Use the “💖 Sponsor on GitHub” button on the site (or github.com/sponsors/bagidea), pick a monthly tier, and confirm — GitHub charges you each month until you cancel.
2. Your logo & link come from your GitHub profile — automatically. Your avatar, display name and link are pulled straight from your GitHub account; there is nothing to send us. To control the link, set the Website field in your GitHub profile (Settings → Public profile). Sponsoring as a GitHub Organization shows your company logo and site.
3. You appear within ~6 hours. As long as you choose “Make my sponsorship public” at checkout, an automated workflow pulls the live list, maps each sponsor to a tier by amount, and updates the supporters wall on the website and the README — sorted by tier, amounts never shown. Private sponsors are respected and not listed.

Everyone joins through GitHub Sponsors. The only exceptions are featured partners added by hand (e.g. WARRIX, pinned first); Reuannamphung is shown as a courtesy until they move to GitHub Sponsors.

CLI reference

The installer puts bagidea on your PATH. It talks to the running office and can start it. A few highlights:

FAQ

Does it cost money to run?

The app is free and open source (MIT). Agents run through your own Claude Code login, so usage follows your existing Claude account or subscription — there is no separate BagIdea fee.

Is my code/data sent anywhere?

The daemon runs locally on 127.0.0.1. Agents are Claude Code sessions, so they use Claude like any Claude Code project. Optional features (voice, image, realtime) use your own OpenAI/Gemini keys only when you enable them.

Which platforms are supported?

Windows 11, macOS 13+ (beta), and Linux (experimental) today.

Can I build my own plugin?

Yes — fork the official template repo. A person or an agent can build a working plugin from it in minutes; the full spec is in the plugin guide.