Documentation

What is sustn?

sustn is a native macOS desktop application that acts as a background conductor for AI coding agents. Instead of waiting for you to open a terminal and type a prompt, sustn continuously monitors your repositories, identifies improvements, and executes them autonomously — all using your existing Claude Code subscription.

Every change lands as a branch. Nothing touches your main branch without your explicit approval. You review the work, create a pull request with one click, and merge when you're ready.

Core Philosophy

Every AI coding tool today follows the same pattern: you prompt, it responds. This reactive model means the agent only works when you're actively driving it. When you're not prompting, your subscription tokens go unused. The backlog grows.

sustn takes a different approach. It's proactive. The agent understands your codebase. It maintains a living backlog of improvements. It picks up work when budget is available and delivers results you can approve or discard. You stay in control, but you're no longer the bottleneck.

Getting Started

Get up and running with sustn in under five minutes. This guide walks you through prerequisites, installation, and your first project setup.

Prerequisites

sustn requires the following tools installed on your machine:

Installation

Download the latest sustn release for macOS. The app ships as a standard .dmg installer.

git clone https://github.com/sustn/sustn.git
cd sustn
nvm use 22
pnpm install
pnpm tauri:dev

The application supports three build environments:

Onboarding

When you first launch sustn, you'll be guided through a four-step onboarding flow:

Core Concepts

Understanding these foundational concepts will help you get the most out of sustn.

Projects & Repositories

A project in sustn corresponds to a Git repository on your machine. Each project has its own task backlog, scan history, and configuration. Projects appear in the sidebar and can be reordered by dragging.

When you add a project, sustn tracks:

• The local filesystem path to the repository
• The default branch (usually main or master)
• The base branch for creating feature branches
• The remote origin URL
• When the project was last scanned and worked on

Tasks & the Backlog

Tasks are the fundamental unit of work in sustn. Each task represents a specific improvement or fix that the agent has identified (or that you've manually created). Tasks have two origins:

The Agent Engine

The engine is the core runtime that coordinates all automated work. Built in Rust, it manages the lifecycle of scanning and task execution through several specialized modules:

The engine runs as a managed state within the Tauri application, communicating with the frontend through IPC commands and event emitters.

Budget Management

sustn is designed to use your existing Claude Code subscription — specifically the tokens you're not using. It reads Claude's usage statistics and calculates how many tokens are available for background work.

The budget module reads from Claude's stats-cache.json file, which tracks daily token consumption. When tokens are exhausted, sustn gracefully pauses until more budget becomes available.

Scanning & Discovery

Scanning is how sustn builds your task backlog. The scanner analyzes your entire codebase and identifies concrete improvements — from missing test coverage to security vulnerabilities.

How Scanning Works

sustn uses a sophisticated two-pass scanning system to balance speed with depth:

What Gets Detected

The scanner identifies improvements across nine categories:

Category weights are used by the prioritizer to rank tasks. Security issues are weighted 5x more heavily than documentation improvements, ensuring critical fixes surface first.

Scan Frequency

Configure how often sustn scans your repositories:

Task Management

The task system is at the heart of sustn. It's where discovered improvements are tracked, prioritized, and managed through their entire lifecycle.

Task Lifecycle

Every task moves through a defined set of states:

Task Properties

Each task carries detailed metadata to help you understand and manage it:

Prioritization

sustn's prioritizer uses a multi-factor scoring system to decide what to work on next. Both projects and tasks are scored independently.

You can override automatic prioritization at any time by dragging tasks to reorder them or setting manual priorities.

Automated Execution

When the scheduler and budget allow, the engine's worker module picks up tasks and executes them through a structured three-phase workflow.

Work Phases

Every task goes through three distinct phases, each with a 30-minute timeout:

// Implementation output
{
  files_modified: ["src/auth/middleware.ts", "src/auth/middleware.test.ts"],
  summary: "Added input validation to auth middleware...",
  tests_added: true
}

// Review output
{
  passed: true,
  feedback: "Implementation correctly addresses the task...",
  issues: []
}

Retry & Error Handling

If the review phase fails or an error occurs during implementation, the worker automatically retries up to 2 times. Each retry includes the error feedback from the previous attempt, giving Claude context to fix its approach.

On failure, the branch is cleaned up and the agent returns to the original branch. The error details are stored in the task's lastError field for debugging.

Code Review & Pull Requests

Once the agent completes a task, the changes land on a feature branch. sustn provides a full code review experience right inside the app.

Diff Viewer

The built-in diff viewer shows exactly what changed, presented in a familiar side-by-side format:

• Changed files sidebar — Browse all modified files with addition/deletion stats
• Side-by-side diff — View old and new code next to each other with syntax highlighting
• File content viewer — Read the full file with syntax highlighting for deeper context
• Lines added/removed — Quick stats on the scope of changes

Creating Pull Requests

When you're satisfied with the agent's work, you can create a pull request with one click. sustn uses the GitHub CLI under the hood, so the PR appears in your repository just like any other.

Configuration

sustn is highly configurable. Global settings apply to all projects by default, and individual projects can override specific settings.

General Settings

Git & Branch Settings

# slug style (default)
sustn/add-error-handling-to-auth-middleware

# short-hash style
sustn/a3f8b2

# task-id style
sustn/task-01j8k2m4n5

Scheduling

Control exactly when the agent is allowed to work. Three scheduling modes are available:

Schedule: Mon-Fri, 22:00 - 06:00
Timezone: America/New_York

Budget Controls

Per-Project Overrides

Any global setting can be overridden on a per-project basis. This lets you apply different strategies to different repositories:

• Agent Preferences — Free-form text instructions that Claude considers when working on this project (e.g., "Always use TypeScript strict mode").
• Scan Preferences — Custom instructions for how the scanner should analyze this project (e.g., "Focus on test coverage").
• Base Branch — Override the default base branch for this project.
• Remote Origin — Use a different git remote.
• Budget Ceiling — Set a project-specific token limit.

Architecture

For contributors and technically curious users, here's a deep dive into how sustn is built.

Tech Stack

Data Flow

Data flows through the application in a predictable pattern:

The Tauri IPC layer provides type-safe communication between the React frontend and Rust backend. Events flow bidirectionally — the backend emits events (like scan progress) that the frontend subscribes to through TanStack Query's event integration.

Engine Modules

The agent engine is built from six specialized Rust modules, each with a clear responsibility:

engine/
├── mod.rs          Core EngineState, Claude CLI invocation
├── scanner.rs      Two-pass codebase analysis
├── worker.rs       Task execution (plan → implement → review)
├── scheduler.rs    Time window & schedule validation
├── prioritizer.rs  Project & task scoring algorithms
├── budget.rs       Token usage tracking & budget calculations
├── git.rs          Git operations wrapper
└── db.rs           Direct database operations from Rust

The engine state is managed as a thread-safe singleton using Arc<EngineState>, shared across all Tauri command handlers. It tracks the current running status, active task, and cancellation token for the scheduler loop.

pub struct EngineState {
    pub running: RwLock<bool>,
    pub current_task: Mutex<Option<CurrentTask>>,
    pub cancel_token: Mutex<Option<CancellationToken>>,
}

Claude CLI is invoked as a subprocess with the --print and --output-format json flags, enabling structured output parsing. Each invocation has a 30-minute timeout to prevent runaway processes.