# How to Vibe Code Your Own Uncircle (and Stop Paying for It)

> Native workspace for repos and terminals

- Site: https://uncircle.app
- Category: Developer Tools
- Platforms: macOS app, Windows app, Linux app
- Verdict: **Solid side project** (68/100 vibecodeable)
- Estimated effort: 2-3 weeks part-time

## Verdict

You can build a personal desktop workspace clone for local agent management, but managing reliable cross-platform PTY lifecycle termination and terminal scraping heuristics will test your patience.

Writing a Tauri wrapper with a sidebar and xterm.js components is straightforward with an AI agent. However, you will hit friction when handling cross-platform pseudo-terminals (PTYs), cleanly killing orphaned child processes spawned by nested shell scripts, and writing regex heuristics that reliably distinguish when an arbitrary CLI agent like Claude Code or Aider is waiting for permission versus actively churning. Since the paid product is only $49 for a lifetime license across 3 devices, building this is strictly a fun exercise for local-first tool customisation rather than an economic shortcut.

### What you can't replicate

- The exact design polish and continuous maintenance velocity of the original indie author

## What it does

A native desktop workspace designed for managing local software development stacks that incorporate AI coding agents alongside traditional dev servers, databases, and worker processes.

### Core features

- Multi-service process orchestration via configuration files (`uncircle.yml`)
- Pseudo-terminal (PTY) spawning and full xterm.js ANSI terminal emulation
- Real-time log scraping and heuristics for dynamic local URL extraction
- Intelligent process monitoring and auto-restart loops for crashed background servers
- Agent state detection (working, waiting for user input, crashed, done) per provider
- Native OS notifications on process failures or completion
- External editor integration (Cursor, VS Code, Zed, file manager)
- Compact collapsible sidebar project launcher and home dashboard

## The business

### Pricing

- Free: Free — Up to 3 projects free forever with all features included.
- Lifetime: $49 one-time — Unlimited projects and devices.

Founded 2026.
Team size: 1.

## The hard parts

- Cross-platform PTY management and child process lifecycle cleanup to prevent orphaned shell processes
- Robust heuristic log parser that accurately detects agent states across distinct CLI dialects without lagging UI performance
- Real-time output stream parsing to instantly discover ephemeral URLs like `http://localhost:5173`
- Native window frame styling, global keyboard shortcuts (e.g., ⌘B, ⌘1-9), and system tray interactions in Tauri

## How to vibe code Uncircle

### Prerequisites

- Node.js (free): Required to run the frontend build tooling and package management for Tauri.
- Rust toolchain (free): Required by Tauri v2 to compile the native desktop backend and manage OS processes.
- Cursor (free): Primary AI code editor used to vibecode the application.

### Recommended AI tools

- Claude Code: Unmatched at architecting complex Rust/TypeScript Tauri applications and managing multi-file changes.
- Cursor: Ideal for iterative UI work, styling the sidebar, and adjusting React/Tailwind components.

### Stack

- Frontend: React + TypeScript + Tailwind CSS + xterm.js
- Backend: Rust (Tauri v2 core, portable-pty, async tokio command runner)
- Database: Local SQLite file via Tauri store plugin (for app state and project configurations)
- Auth: None (local-first native application)
- Payments: None (personal use only)
- Other: portable-pty Rust crate, serde for uncircle.yml config parsing

### Hosting

- Local machine (Native desktop application runtime executed locally on macOS, Windows, and Linux): $0/mo

### Build guide

1. **Scaffold Tauri v2 Desktop App with React and Tailwind** — Initialize the Tauri project structure using React, TypeScript, and Tailwind CSS, setting up the foundational window chrome and layout shell.

```
Create a new Tauri v2 application using React, TypeScript, and Tailwind CSS. Configure the Tauri configuration file (`tauri.conf.json`) to have a frameless or custom-styled native window header with hidden default title bar on macOS and Windows, while preserving native window resizing and drag regions. Set up a clean two-column layout with a dark/light theme toggle that applies before first paint to prevent white flashes. Structure the project directories for frontend components (`src/components`), Tauri backend commands (`src-tauri/src`), and type definitions.
```

2. **Implement Project Config Parser (`uncircle.yml`)** — Build the configuration parser in Rust to read project definitions, agent presets, and command stacks from local YAML files.

```
Implement a Rust module in the Tauri backend using `serde` and `serde_yaml` to parse `uncircle.yml` project files. Define data structures for projects, agent presets (Claude Code, Cursor CLI, Codex, OpenCode, Copilot), dev server processes, working directories, and environment variables. Expose Tauri commands to scan a designated workspace directory for valid `uncircle.yml` files, validate their schemas, and return structured project objects to the React frontend.
```

3. **Build the PTY Process Orchestrator in Rust** — Integrate pseudo-terminal spawning and process management to execute multiple concurrent shells and background workers safely.

```
Integrate the `portable-pty` crate into the Tauri Rust backend to manage pseudo-terminals (PTYs). Create a thread-safe process manager struct that can spawn child shell processes (bash, zsh, powershell), pipe standard input and output streams back to the frontend via Tauri events, and resize terminal dimensions dynamically. Implement a robust process shutdown mechanism that recursively terminates child and orphan processes across macOS, Windows, and Linux kernels when a user stops a stack, preventing zombie processes.
```

4. **Integrate xterm.js Terminal UI and ANSI Rendering** — Connect frontend xterm.js instances to backend PTY data streams with full ANSI color support, search, and copy/paste.

```
Build a React terminal component wrapping `xterm.js` along with the `FitAddon` and `WebLinksAddon`. Establish bidirectional communication where keystrokes in the xterm instance send data to the backend PTY command via Tauri events, and backend output streams write directly to the active terminal buffer. Ensure full ANSI color support, scrollback history, search, and mouse selection work seamlessly. Add visual tabs to switch between active terminal sessions, agents, and background worker logs within a project view.
```

5. **Add Real-Time Log Scraping and URL Detection Heuristics** — Inspect terminal output streams in real-time to extract dynamic local web addresses and turn them into clickable pills.

```
Write a lightweight heuristic log-scraping utility in TypeScript/Rust that inspects incoming terminal lines for local addresses (such as `http://localhost:XXXX`, `http://127.0.0.1:XXXX`, or `https://...`). When a URL is detected in process output logs, emit an event to display a clickable pill badge at the top of the process header that opens the URL in the default system browser.
```

6. **Implement Agent State Heuristics and Auto-Restart Logic** — Detect agent execution states (working, waiting for input, crashed, done) and implement auto-restart capabilities for crashed dev servers.

```
Implement state-detection heuristics for AI coding agents by analyzing output streams and exit codes. Map states to a unified dot vocabulary: pulsing for working, amber for waiting for user permission/input, hollow ring for finished, and red for crashed. Add an auto-restart supervisor loop in the backend that monitors designated dev servers and worker processes, automatically restarting them upon unexpected crashes while notifying the user via Tauri native OS notifications.
```

7. **Polish Navigation, Home Launcher, and Editor Integration** — Build the central Home project launcher, collapsible sidebar, keyboard shortcuts, and one-click external editor launching.

```
Build a searchable Home launcher view that lists all registered projects and active sessions with colored ring monograms. Implement a collapsible sidebar toggleable via `⌘B`, shortcut badge alignment when holding `⌘`, and shortcut navigation (`⌘1-9` for sessions, `⌘0` for Home). Add Tauri backend commands to launch external editors (Cursor, VS Code, Zed) or reveal project directories in the system file manager with a single click.
```

### Cost vs paying

**Starting costs (one-time):**

- Apple Developer account (optional for macOS app code-signing): $99/yr
- Total: ~$20 to $119

**Ongoing costs (monthly):**

- Total: $0/mo

- Paying for the SaaS instead: $49 one-time
- Build time: 25-35 hours
- AI tool credits: ~$20 (Claude Pro / Cursor Pro)
- Break-even: N/A (lifetime purchase)

## Sources

- [Uncircle Official Website](https://uncircle.app)