# Soulgent

> Soulgent turns every Claude Code, Codex and WorkBuddy session on a Mac into a visible character showing who is working, done, or waiting for you.

Soulgent is an open-source macOS menu-bar app and companion phone web app that represents each agent session on your Mac as a character with a name, look and mood. It reads session state from Claude Code, Codex and WorkBuddy so you can see at a glance who is working, who has finished, and who needs a decision. The repository's latest listed release is v0.1.0.

## What It Is

Soulgent is a session-monitoring and status-visualization tool for people who run many long-lived coding-agent sessions. It has two parts that share one live picture of your sessions: Soulgent for Mac, a native menu-bar app with a floating window, and Soulgent App, a mobile web app (its chat page is called SoulChat) that runs on your Mac in Docker and can be added to an iPhone home screen.

## Scenes and Session States

The Mac app offers three scenes. Seaview is a Blender-rendered seaside office with four islands for four teams, where sessions needing a decision walk to your desk, queue and knock, and sub-agents appear as small figures beside the desk. The Office shows finished sessions waiting on sofas, and the Duty Room shows one card per session grouped by what it needs from you. Characters come from the Petdex library, and Blaze Mode highlights Claude Code sessions whose model name contains "fable".

## Teams and Click-to-Jump

Sessions are assigned to teams (work zones) by naming them in a zone-system-task pattern and defining a zone table in ~/.claude/workzones.json, with a Leader at desk 1. With Orca installed, clicking a character jumps to its session, and Spotlight marks the session you are typing in.

## Replying from Your Phone

Soulgent App shows sessions in a list with context-window rings, team effects, tool-activity animations and sub-agent cards, and supports replying, answering questions, approving commands and sending files. Per the README, replies currently work only for Claude Code sessions running in Orca; Codex and WorkBuddy sessions show state and summary only. The server is reached over HTTPS on the local network, and only push notifications leave it via Apple's or Google's push service.

## Setup Path

Installation builds the app from source with app/build.sh and tools/install.sh, then installs characters with a script, sets up teams, and opens Seaview. It requires macOS 14 or later on Apple Silicon, Xcode Command Line Tools and Node.js 20 or later. Docker is needed only for Soulgent App.

## Features
- Visualizes each Claude Code, Codex and WorkBuddy session as a character
- Seaview, Office and Duty Room scenes
- Sessions needing a decision queue and knock at your desk
- Team (work zone) grouping with Leaders via ~/.claude/workzones.json
- Sub-agent display beside session desks
- Click-to-jump to sessions via Orca
- Blaze Mode for Fable-model Claude Code sessions
- Mobile web app with push notifications for replying, approving commands and sending files
- Characters from the Petdex library
- English, Simplified Chinese and Traditional Chinese

## Integrations
Claude Code, Codex, WorkBuddy, Orca, Petdex, Docker, Sidecar

## Platforms
WINDOWS, MACOS, ANDROID, IOS, WEB, API, CLI

## Pricing
Open Source

## Version
v0.1.0

## Links
- Website: https://github.com/Ericcc0321/soulgent
- Documentation: https://github.com/Ericcc0321/soulgent#readme
- Repository: https://github.com/Ericcc0321/soulgent
- EveryDev.ai: https://www.everydev.ai/tools/soulgent