∿ 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.