ReasonFirst

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.

Related MCP server: GitLab MCP Server

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 external users, start with the generic fully chat-based E2E practice. It uses placeholders for your own GitLab host/project and keeps the human merge decision separate from automated execution. On macOS networks that require an HTTP(S) proxy, use the documented session-scoped launchd proxy sync rather than writing proxy credentials into a plist.

Install — packaged or source

Both installation routes are first-class and converge on the same setup/state model.

Normal-user packaged route (after v0.5.1 publication and successful release-asset attachment):

uv tool install https://github.com/phoenixjyb/reasonFirst/releases/download/v0.5.1/chatgpt_selfhosted_gitlab_mcp-0.5.1-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. The source route remains fully supported for contributors, audits, private patches and editable installs. Both use the same private config, SetupState, project grants and tunnel identities; switching route does not require recreating account resources. See Install & update · 中文.

Guides by task

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

The source/package version is 0.5.1. This identifies the source, not proof of a published release or downloadable assets. After maintainer publication, the v0.5.1 tag identifies the released commit; record the exact commit SHA as well as the package version in bug reports. See 0.5.1 release notes and CHANGELOG.md. The published v0.5.0 tag and its historical release notes remain the frozen earlier baseline.

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.