Give the next agent a clear starting point

The repository starts with AGENTS.md. It describes OpenSurge as a macOS gateway and control plane, identifies mihomo as the proxy engine, and points to the relevant architecture and validation documents. An agent working on TUN routing can follow a focused reading path before touching the implementation.

That entry point also records constraints that a plausible-looking patch could otherwise miss: TUN is the supported transparent proxy path; the Web GUI, menu bar app, and CLI should reuse the Go business rules; high-risk network changes require evidence from the lab. These rules help a contributor understand which existing decisions the change must respect.

Keep project knowledge beside its sources

The Agent Wiki has two layers. Its sources directory holds stable project facts, decisions, and validation contracts. Its wiki directory provides concise, linked context pages that guide an agent back to the code and documents that establish those facts.

A routing task can begin with a concept page, follow the relevant decision, and then inspect the compiler or lifecycle code. This makes the reasoning behind an implementation discoverable across sessions, while keeping the source of truth available for verification.

Project context leads to implementation and validation, with reviewed findings returning to the Agent Wiki
Follow the context to its sources, collect the required evidence, and carry reusable findings into the next task. Open the diagram for a larger view.
The context map in the product repositorytext
AGENTS.md
README.md
docs/agent-wiki/
  sources/
    project-brief.md
    decisions/
    validation/
  wiki/
    index.md
    concepts/
Agent Wiki structure and maintenance rulesHow stable sources and reviewed context pages are organized in the repository.

Make the running system inspectable

The Web GUI is the main operator interface. The omg CLI also provides structured interfaces for diagnostics and automation: status, doctor, leases, logs, policies, connections, providers, and snapshot support JSON output.

A snapshot brings gateway status, checks, leases, recent logs, and mihomo observations together. When the mihomo API is unavailable, the aggregate records that failure within the affected fields. An agent can use those observations to distinguish a stopped service, an invalid configuration, and an unavailable backend before proposing a fix.

  • Use structured state to identify what is configured and what is actually running.
  • Use connection and log evidence to check the path traffic took.
  • Report missing evidence explicitly when a service or API cannot be inspected.
Read-only inspection with the configured CLIshell
omg status --format json
omg doctor --format json
omg snapshot --format json

Connect each change to the right proof

The validation map answers a practical question: what needs to pass before we can describe this behavior as verified? Unit tests protect configuration and business rules. Host-network gates exercise the macOS gateway. TUN, device policies, downstream IPv6, and Tailscale each have more specific gates.

For example, a Tailscale rule compiler test can check target and source matching. A successful mihomo configuration check shows that the core accepts the generated YAML. The dedicated Tailscale Lab then sends traffic from two downstream clients and checks the managed path and the unauthorized rejection. Each step supports a different conclusion.

Inside the Virtual LabA shared test environment for connectivity, configuration, device policies, IPv6, and Tailscale.Repository validation mapThe change categories, commands, and evidence required for each gate.

Carry useful findings into the next task

When a change alters a lifecycle invariant, routing decision, or validation contract, the workspace rules call for updating the corresponding source material and wiki pages with the implementation. A reusable lesson from an incident can then guide the next contributor.

One-off logs, temporary command output, unverified guesses, and ordinary TODOs stay outside this stable knowledge layer. The Agent Wiki is currently maintained manually. Its directory structure anticipates a possible compiler workflow, but automatic knowledge compilation is not a current project capability.

A reviewable workflow for contributors

The intended loop is concrete: read the entry point, follow the relevant context, inspect the source and current state, make a scoped change, run the applicable checks, and record what the evidence establishes. Documentation helps choose the test; the test result supports the claim; reviewed findings improve the next task’s context.

For users, the benefit is traceability. A network feature has an explanation of how it works, constraints that the implementation must preserve, and a way to check its behavior. The workspace makes those relationships easier for both human and AI contributors to follow.

Read AGENTS.mdThe contributor entry point, product boundaries, and required validation rules.Explore the Agent Wiki indexGateway lifecycle, control-plane architecture, routing concepts, and structured CLI contracts.

FAQ

Questions people ask before changing the network

Does this require one particular AI coding tool?

The core context is stored in Markdown alongside the code, and diagnostics are exposed through the CLI. A contributor or tool that can read the repository can follow it; individual tools may need their own setup to load the entry point automatically.

Is the Agent Wiki automatically generated?

It is currently maintained manually. The repository describes a possible future compiler workflow, while today’s stable source material and context pages are updated and reviewed with relevant changes.

Can passing unit tests establish that a gateway change works?

Unit tests establish the rules they exercise. Claims about actual macOS networking require the relevant host-network, TUN, IPv6, Tailscale, or real-device evidence specified by the validation map.