Worktrunk Network Access Policy: A Local-First Approach to Bounding Network Access

Worktrunk follows a local-first architecture that treats every network operation as an explicit exception, ensuring standard Git commands run entirely offline while remote data fetches require deliberate opt-in via CLI flags.

Worktrunk is a high-performance Git workflow CLI designed for predictable behavior in disconnected environments. Its network access policy enforces a strict boundary where the tool prefers pure Git data from the local filesystem, and any step requiring remote connectivity is clearly identified, cached, and deferred. This design guarantees that routine commands remain fast and reliable regardless of network availability.

Three-Layer Enforcement Architecture

The policy is implemented through three distinct architectural layers that classify, isolate, and execute network operations only when absolutely necessary.

Command-Task Classification

Worktrunk categorizes every work item by its network requirements before execution begins. In src/commands/list/collect/types.rs, the TaskKind enum provides an is_network() method that identifies tasks requiring remote access. The task collector in src/commands/list/collect/mod.rs sorts these network tasks to run last, ensuring that local Git operations never block waiting for remote data. This scheduling guarantee means that branch listings, status checks, and local diff calculations complete immediately even if the network is congested or unavailable.

Single Fall-Through Helper

The only implicit network call in the entire codebase resides in src/git/repository/mod.rs. The Repository::default_branch() method may execute git ls-remote once per repository to discover the default branch name, but the result is cached with a TTL (time-to-live) and never re-queried automatically. This one-off lookup represents the sole exception to the explicit opt-in rule, and it occurs only when Worktrunk encounters a repository for the first time.

Explicit Network Commands

All other network I/O is strictly opt-in through specific CLI flags. Features like CI status, pull request details, and LLM-generated summaries trigger network operations only when requested:

• CI Status: src/commands/list/ci_status/* handles asynchronous fetches using a bounded thread-pool
• PR Picker: src/commands/picker/prs.rs streams gh pr list results when --prs is specified
• LLM Summaries: src/summary.rs queries remote models only when explicitly invoked

These operations implement a cache-first strategy where results are persisted to disk, ensuring subsequent runs read locally cached data without touching the network.

Testing Guards and Observability

Worktrunk provides mechanisms to audit and restrict network access during development and runtime.

Testing Isolation

The test harness in src/testing/mod.rs disables all Git transports by default via the GIT_ALLOWED_PROTOCOLS environment variable. The helper function allow_network_transports() serves as a deliberate gate that test authors must invoke to permit network access in specific test cases. This prevents accidental remote calls during CI runs and ensures that unit tests validate local-only code paths.

Chrome Tracing Integration

For production observability, src/trace/chrome.rs marks any command touching the network with the network category in Chrome trace output. This allows developers to audit exactly when Worktrunk contacts remotes by inspecting the cat = "network" annotations in performance traces.

Core Principles of the Network Policy

The bounding of network access in Worktrunk follows five immutable rules derived from the source code:

• No Hidden Background Polling: Worktrunk never contacts remotes while rendering prompts or after fresh clones unless the user explicitly requests remote data.
• One-Off Remote Lookup: The default-branch detection in Repository::default_branch() may hit the wire once; subsequent uses read from cache.
• Explicit Opt-In: Network-heavy features require deliberate flags such as --full or --prs.
• Graceful Degradation: CI-status fetches treat rate limits and connectivity errors as retriable, displaying an "error" placeholder rather than aborting the command.
• Cache-First Strategy: All network data is written to disk; subsequent executions read the cache without network round-trips.

Practical Usage Examples

The following commands demonstrate the boundary between local and network operations:

# Fast, local-only listing (no network)

wt list               # Shows branches, status, etc. – all Git-local

# Explicitly request remote CI status (network)

wt list --full        # Adds the CI column; network is used only for that column

# Show PR information (network) in the interactive picker

wt switch --prs       # Fetches gh pr list and streams results; cached per PR

# Force a remote default-branch lookup (normally cached)

wt list --debug default-branch   # Triggers the one-off git ls-remote call

Summary

• Worktrunk enforces a local-first network access policy where network tasks are classified via is_network() and scheduled last to prevent blocking.
• The only automatic remote call is Repository::default_branch() in src/git/repository/mod.rs, which caches results indefinitely after the first lookup.
• All other network access requires explicit CLI flags (--full, --prs) and uses asynchronous, bounded thread-pools with disk caching.
• Unit tests disable network transports by default via src/testing/mod.rs, requiring deliberate opt-in through allow_network_transports().
• Network activity is auditable through Chrome traces marked with the network category in src/trace/chrome.rs.

Frequently Asked Questions

Does Worktrunk work completely offline?

Yes. Standard commands like wt list, wt switch, and wt statusline operate entirely on local Git data and require no network connectivity. Only features explicitly requesting remote information—such as --full for CI status or --prs for pull request listings—attempt network access, and these gracefully degrade to cached data or error placeholders when offline.

What is the only network call that happens automatically?

The Repository::default_branch() method in src/git/repository/mod.rs may run git ls-remote once per repository to determine the default branch name. This occurs only when Worktrunk first encounters a repository, and the result is cached with a TTL. No other automatic background polling or synchronization occurs.

How does Worktrunk handle network failures?

Network operations use a graceful degradation strategy. When fetching CI status or PR details, rate limits and connectivity errors are treated as retriable. Rather than aborting the entire command, Worktrunk displays an "error" placeholder in the relevant column and continues with locally available data. This ensures that temporary network issues never block routine Git workflows.

Where can I see which commands used the network?

Worktrunk integrates with Chrome tracing to mark network operations. Any command performing remote I/O is annotated with cat = "network" in the trace output from src/trace/chrome.rs. Additionally, using --debug flags reveals when cached default-branch data is refreshed or when remote lookups occur.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}