README.md

August 23, 2026 · View on GitHub

∿ PyCode

Fast Native Desktop & Web Development GUI for Py-Agent
Powered by the Agent Client Protocol (ACP) over stdio JSON-RPC.

Overview

PyCode is a cross-platform React Desktop & Web development workspace for Py-Agent, forked from pingdotgg/t3code.

Native ACP Protocol: Speaks stdio JSON-RPC 2.0 directly to py-agent with zero daemon overhead.
Inherited CLI State: Automatically adopts runtime settings (/tts voice, reasoning budgets, model configs, YOLO mode) configured in your active py-agent terminal session.
Thought Formatting: Renders reasoning and thought processes into clean markdown quote blocks (> *Thinking...*).
Theme Aurora Glow: Hardware-accelerated Gemini-inspired ambient lighting behind the composer that adapts dynamically to all color palettes.
CLI Suspension: Launch /pyc from terminal to pause CLI and resume automatically on window close.
Dual Execution: Runs as an Electron Desktop app or local browser WebUI (http://localhost:3773).
Active Development: New features and agent capabilities actively being added.

React Desktop IDE

Architecture & ACP Flow

  ┌────────────────────────────────────────────────────────┐
  │                   PyCode GUI (Electron)                │
  │     [React UI] ◄──► [PyAgentAdapter] ◄──► [ACP Client] │
  └───────────────────────────┬────────────────────────────┘
                              │ stdio JSON-RPC 2.0 (ACP)
                              ▼
  ┌────────────────────────────────────────────────────────┐
  │                 Py-Agent Headless Bridge               │
  │     [plugins/pycode/bridge.py] ◄──► [agent_core.py]    │
  └───────────────────────────┬────────────────────────────┘
                              │ HTTP SSE / Tools
                              ▼
  ┌────────────────────────────────────────────────────────┐
  │           llama-server / Cloud API Cascade             │
  │    (LFM2.5-8B, Qwen3.6-35B, DeepSeek, Claude, GPT)     │
  └────────────────────────────────────────────────────────┘

Key Features

Feature	Description
Ambient Aurora Glow	Optional Appearance toggle for GPU-composited, Gemini-inspired ambient lighting behind the composer with dynamic theme-reactive palette syncing.
Minimal Interface	Stripped top-bar branding for a clean, distraction-free workspace.
Custom Vector Icon	Integrated 18px line-art interlocking Python loop matching native OpenAI/Claude visual density.
ACP Provider Driver	First-party `pyagent` driver registered across server, contracts, and frontend layers.
Thought Traces	Formats model reasoning and thinking into clean markdown quote blocks (`> Thinking...`).
Dynamic Workspaces	Automatically syncs project roots, AST codebase maps (`index-map`), and `.agent/tpm.md` facts.
Fast CLI Shortcuts	Launch directly from `py-agent` with `/pyc` or `/pycode` (desktop) and `/pyc web` (browser).

Upstream Fork Manifest

All modifications are isolated to ensure updates from pingdotgg/t3code merge cleanly:

Layer	File Path	Modification Summary
Driver	`apps/server/src/provider/Drivers/PyAgentDriver.ts`	Registered `PyAgentDriver`, snapshot metadata, & reasoning options
Adapter	`apps/server/src/provider/Layers/PyAgentAdapter.ts`	Effect ACP session lifecycle, scope isolation, & `item.started` events
Runtime	`apps/server/src/provider/acp/PyAgentAcpSupport.ts`	Process spawner for `plugins/pycode/bridge.py`
Drivers Registry	`apps/server/src/provider/builtInDrivers.ts`	Added `PyAgentDriver` to `BUILT_IN_DRIVERS`
Brand Chrome	`apps/web/src/components/sidebar/SidebarChrome.tsx`	Clean zero-branding top sidebar
Vector Icons	`apps/web/src/components/Icons.tsx`	Flat monochrome `PyAgentIcon` vector component
Icon Mapping	`apps/web/src/components/chat/providerIconUtils.ts`	Mapped `pyagent` driver keys to `PyAgentIcon`
Global Brand	`apps/web/src/branding.ts`	Updated default fallback display name
UI Components	`apps/web/src/components/chat/ChatComposer.tsx`	Added GPU-composited theme-reactive ambient aurora glow & solid surface styling
Settings UI	`apps/web/src/components/settings/SettingsPanels.tsx`	Added `ChatGlowRow` toggle switch under Appearance settings
Contracts	`packages/contracts/src/model.ts`	Declared `PYAGENT_DRIVER_KIND` & `local-model` defaults
Contracts	`packages/contracts/src/settings.ts`	Added `PyAgentSettings` and `chatGlow` schema defaults & patch types

Setup & Installation

Prerequisites

Node.js: v20+ or v22+
pnpm: v9+ (corepack enable && corepack prepare pnpm@latest --activate)
Python 3.10+ (with py-agent configured)

# Automatic setup (if using py-agent)
install-pycode
# (or run: ~/.config/py-agent/plugins/pycode/setup.sh)

# Or clone & build manually
git clone https://github.com/j5onrf/pycode.git ~/.config/pycode
cd ~/.config/pycode
pnpm install
pnpm build

Launching PyCode

Launch Method	Command	Description
From Py-Agent CLI	`/pyc` (or `/pycode`)	Suspends CLI and opens native Electron Desktop GUI
From Py-Agent CLI (Web)	`/pyc web`	Suspends CLI and opens WebUI in default browser
Direct Shell (Desktop)	`~/.config/py-agent/plugins/pycode/launch.sh`	Launches Electron GUI for current directory
Direct Shell (Web)	`~/.config/py-agent/plugins/pycode/launch.sh web`	Starts WebUI server on `http://localhost:3773`

License

Distributed under the MIT License. Built for the py-agent ecosystem.