reasonFirst

ReasonFirst

Unreleased source: optional Antigravity CLI (agy) worker, interactive terminal only; not included in the v0.5.3 package.

English · 简体中文 · Documentation site · First-time setup · Documentation index

Reasoning-first coding orchestration. Use your strongest reasoning model for reasoning. Let coding agents do the coding.

ReasonFirst puts normal ChatGPT (or another deliberately chosen strong reasoning interface) at the front of the engineering loop and keeps coding agents replaceable. ChatGPT reads evidence, reasons about architecture and root cause, and defines the task boundary; ActualCoder turns that approved intent into a controlled Git worktree handoff for Codex CLI, GitHub Copilot CLI, or Codex Desktop/App Server, then returns validation, Merge Request, CI, and bounded evidence for review.

The goal is to spend reasoning capacity on architecture, diagnosis, and review while delegating implementation iterations. ReasonFirst is not a model proxy, quota-transfer service, or auto-merge bot. It makes no direct model-inference calls; external coding tools use their own authentication and billing. Cost savings are a design goal, not a measured guarantee.

Early-stage developer tooling: use trusted repositories on a trusted development host. A Git worktree is not a security sandbox. Read SECURITY.md before using real credentials or executing repository code. A private MCP endpoint still returns selected data to the connected reasoning service; obtain the relevant data-sharing approval.

Primary workflow: reason first, execute second

ReasonFirst is designed around one primary loop, not several co-equal product modes. Normal ChatGPT is the default reasoning surface: use its strongest available reasoning capability for architecture, diagnosis, task decomposition, scope control, acceptance criteria, and review. Coding agents are execution workers.

ChatGPT / strong reasoning interface
        ↓ read repository / MR / CI evidence
reason about architecture, root cause, scope and acceptance
        ↓
durable task contract (TaskSpec)
        ↓
ReasonFirst control layer
        ↓
codex-cli / copilot-cli / codex-desktop
        ↓
controlled implementation + validation + MR / CI
        ↓
bounded evidence (diff / EvidencePack / CI)
        ↓
ChatGPT + human review
        ↓
continue, revise, or merge

The read-only GitLab MCP supplies repository/MR/CI evidence to the reasoning layer. ActualCoder and the optional Bridge Preview are execution/control surfaces underneath that loop. Bridge Preview is more privileged and should be enabled deliberately.

Secondary operational capability: ActualCoder can be invoked directly from a terminal, CI repair flow, IDE, or another client. That is useful for testing, recovery, automation, and portability, but it is a byproduct of the decoupled architecture—not the primary ReasonFirst product story.

Validated chat-only loop

The full ChatGPT-first path has now been exercised end to end against a synthetic GitLab practice repository: live source grounding, pinned TaskSpec, one managed workspace, Bridge-managed Codex App Server execution, reviewed diff, snapshot-bound finish preview, explicit human publication approval, Merge Request creation, matching-HEAD CI, and EvidencePack review. The coding worker did not publish by itself and ReasonFirst did not auto-merge.

For a first installation, start with the standard route: ChatGPT reads and discusses the project, then terminal ActualCoder hands an agreed task to the coding worker. The optional fully chat-based E2E practice requires a workspace that permits Bridge actions. Both routes keep the merge decision with the human. If using a launchd-managed deployment on macOS that requires an HTTP(S) proxy, use the documented session-scoped launchd proxy sync.

Tested on macOS, Windows, and Linux

ReasonFirst has real-machine validation records on macOS, Windows, and Linux, across different versions and scopes. The latest fresh installation used v0.5.2 on Ubuntu 22.04.5: live ChatGPT repository reads, native Git clone/fetch, project-contract validation, and a Codex CLI worker running 10 tests successfully with a clean worktree. The macOS and Windows records cover earlier 0.5.1 installations. See the platform validation matrix for versions, evidence, and remaining checks.

Install — packaged or source

Quick installation from a packaged release and building from source are both available. Both routes converge on the same setup/state model.

Quick packaged install — v0.5.3:

uv tool install --python 3.12 https://github.com/phoenixjyb/reasonFirst/releases/download/v0.5.3/chatgpt_selfhosted_gitlab_mcp-0.5.3-py3-none-any.whl
reasonfirst setup

Source/developer route:

git clone https://github.com/phoenixjyb/reasonFirst.git
cd reasonFirst
uv sync --python 3.12
uv run reasonfirst setup

The packaged route does not require keeping a ReasonFirst checkout. Its versioned assets and download verification are recorded on the v0.5.3 Release. The source route remains fully supported for contributors, audits, private patches and editable installs; the install guide also covers building wheel/source packages. Both use the same private config, SetupState, project grants and tunnel identities; switching route does not require recreating account resources. See Install & update · 中文.

Read before choosing a worker: the Unreleased source change adds --worker later to standard setup. It lets you connect normal ChatGPT for repository reading and discussion, then select a coding worker for an agreed implementation task. The published v0.5.3 wheel and source tag retain their existing wizard worker requirement.

Guides by task

Goal	Guide
Install/update: packaged route or source route	Install & update · 中文
Check real-machine results and platform-specific scope	Platform validation · 三平台实测
First-time ChatGPT connection, from prerequisites to first prompt	Detailed/manual setup · 中文
Already configured: start/status/stop/restart	Tunnel lifecycle · 中文
Confirm a new project's existence/access and obtain an explicit grant	Project access · 中文
Rehearse the reasoning/worker/MR loop	Practice lab · 中文
Run the whole read → edit → MR → CI loop from one ChatGPT conversation	Fully chat-based E2E practice · 中文
Understand interface responsibilities	Workflow · 中文
Execution-engine setup and controlled implementation	CLI quickstart · 中文
Approved requirements and observed results	Manual handoff template · 中文
Current architecture	Architecture · 中文
Design rationale	Design philosophy · 中文
Existing HTTP-to-HTTPS migration	Migration · 中文
Certificates, API redirects and native Git boundaries	Runtime TLS · 中文
Review a PR or update the normal checkout	Local PR review · 中文
Unsupported/advanced profiles or manual startup	Manual operator guide · 中文/Windows
Troubleshoot, contribute or report securely	Troubleshooting · Contributing · Security

How implementation works

ChatGPT / strong reasoning interface: inspect, diagnose, define goal/non-goals/acceptance
    -> persistent task contract and ReasonFirst control
    -> selected worker: codex-cli / copilot-cli / codex-desktop
    -> isolated local worktree or configured SSH workspace
    -> validation + shared review/secret/protected-path gates
    -> EvidencePack / diff / GitLab MR / matching-HEAD CI
    -> ChatGPT + human review decides whether to continue or merge

ReasonFirst now has two distinct MCP surfaces. The original GitLab MCP remains read-oriented for repository/MR/CI inspection. The optional Bridge Preview is a more privileged local orchestration surface: it can prepare managed workspaces, control Codex App Server sessions, expose pending approvals, review unpublished managed diffs/artifacts, and run complete finish previews. SSH mutation/validation is restricted to user-configured targets; arbitrary remote shell execution is not exposed. Experimental remote publication is hidden and disabled by default. See the architecture reference. Persistent core TaskSpec/attempt/EvidencePack support is now on main: task intent and acceptance/non-goals persist with the workspace, attempts are bounded, and actual-coder evidence produces a recursively redacted read-only EvidencePack.

After confirming the real project with the access preflight, follow the CLI quickstart or practice lab. start --no-launch creates a real local workspace and handoff without invoking a coding model; it is not a no-side-effect preview. Do not keep calling start to continue the same task: retain its workspace ID and use resume.

Inspect actual local changes before finish --dry-run, then explicitly approve real finish. Dry-run runs configured validation commands; it means no commit/push, not no code execution. Missing .actualcoder.yaml is allowed but supplies no project-specific tests. A green result without real required tests is not adequate task acceptance.

resume --from-ci returns matching-HEAD failure evidence, not automatic repair execution. Do not invent changes for successful CI. Low-level commit/push commands and some existing generated handoffs do not run every finish gate; retain explicit task boundaries and use the reviewed finish flow. See workflow.

GitLab is the implemented target SCM/CI integration. Hosting this tool's source on GitHub does not imply a GitHub-target task adapter exists. Canonical explicit coding backends are codex-cli, copilot-cli, and codex-desktop; historical codex / copilot remain compatibility aliases.

Try the source without production credentials

For contributors who want only tests/help, install Git and uv. Package metadata requires Python 3.10+; CI uses 3.12. Use a new checkout and stop on errors:

git clone https://github.com/phoenixjyb/reasonFirst.git
cd reasonFirst
uv sync --python 3.12
uv run actual-coder --help
uv run actual-coder-tunnel --help
uv run actual-coder-check-project --help
uv run python -m unittest discover -s tests -v
uv run python scripts/check_repo_secrets.py --history

Tests use temporary repositories, mocked services and loopback fixtures, not production credentials or a real tunnel. Installing dependencies accesses package indexes. Local uv sync can create an untracked uv.lock at this source baseline; preserve it rather than ignoring/resetting unrelated files. MCP/tunnel setup is unnecessary for this local-only test path.

What is available on main

v0.5.3 packages the Linux onboarding fixes: bounded download recovery and clearer doctor discovery, alongside the dated three-platform validation record. See 0.5.3 release notes and the versioned Release for publication and public-download evidence. Source reports should include the exact commit SHA as well as the package version; later Unreleased changes are separate. The published v0.5.2, v0.5.1 and v0.5.0 tags remain frozen, with their 0.5.2, 0.5.1 and 0.5.0 release notes preserved.

Capability	Current scope
Guided setup	Canonical reasonfirst setup, verified project configuration, explicit grants and worker selection; detect-only setup --status
Managed packaged services	Packaged read MCP and optional eligible-workspace Bridge; native tunnel-client supervision with separate tunnel identities and explicit live acceptance
Repair/resume	Reuse healthy recorded runtimes; setup --repair reconnects recorded local state only, without recreating account resources or persisting runtime keys
Managed workspaces	Local Git caches/worktrees plus user-configured SSH workspaces; feature branches, recovery and cross-process mutation locking
Controlled finish	Shared local/remote review gates: validation, reviewability, protected paths, candidate/history secret checks and exact candidate identity
Publication safety	Local reviewed finish is the normal path; SSH publication is exact-tree/destination bound, experimental and default-off
Remote validation	Structured argv execution only inside a user-configured container policy; no arbitrary remote shell and no implicit image pull
Command/CI evidence	Nonzero failures propagate; matching-HEAD CI and bounded/sanitized logs/artifacts
Worker policy	User-owned default backend plus model, effort, sandbox/network and permission controls across Codex CLI, Copilot CLI and Codex Desktop/App Server; Desktop verifies resolved policy and records reroutes
Approval mediation	Codex Desktop approvals are explicit: terminal prompt locally or bounded pending/approve/decline MCP flow; timeout defaults to deny
Project-access preflight	Local allowlist -> GitLab project/ref/files; actionable diagnostics and pinned revision; no automatic grant
Legacy tunnel lifecycle	Existing-profile configure/start/status/stop/restart on macOS/Linux, optional exact Keychain lookup, owned process cleanup; foreground only
HTTPS migration	Offline preview and confirmed local URL updates, private backups and forward recovery
MCP surfaces	Read-oriented GitLab MCP plus optional local Bridge Preview orchestration MCP; see architecture for trust boundaries

Still planned: richer cross-interface TaskSpec/EvidencePack exchange and attempt-result lifecycle, plus further native Git trust/destination-policy work. Workspace mutation locking and shared local/SSH finish gates are already implemented on main. See Architecture for the current boundary.

API/MCP clients reject disabled TLS verification and every API redirect. Configure the final endpoint. GITLAB_CA_BUNDLE adds Python API/MCP trust, not native Git or the migration --check-tls probe. Keep those scopes distinct; see runtime TLS.

Names, compatibility and contribution

ReasonFirst is the project; reasonfirst is the canonical setup/management CLI, and ActualCoder (actual-coder) is the high-level execution CLI. gitlab-agent is lower-level and codingagent is a compatibility alias. Distribution chatgpt-selfhosted-gitlab-mcp, Python package gitlab_agent, private config ~/.config/gitlab-agent/.env and existing workspace paths are intentionally retained. Do not rename managed directories during an update.

Global editable commands follow their source checkout; use a separate worktree for PR experiments. Contributions and reproducible English/Chinese reports are welcome: Contributing, Security reporting, release checklist. Never publish credential files, private source, migration backups or unreviewed logs in issues.

Licensed under Apache License 2.0; see LICENSE. External tools have their own licenses/terms. This is an independent project, not an official OpenAI, GitHub or GitLab product.