feat(mcp): add session spawning helper#292
Merged
forketyfork merged 3 commits intomainfrom Apr 28, 2026
Merged
Conversation
Issue: Implement #291 by adding an MCP entry point that lets external clients ask a running Architect app to create a terminal session. Solution: Add a separate `architect-mcp` stdio server plus a small local control socket owned by the GUI process. The helper validates `spawn_session` calls, forwards them to Architect, and returns structured success or stable error codes. Runtime handles spawning on the main loop so grid changes, focus, and command input stay on the existing session path.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 050793be53
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
Pull request overview
Adds an architect-mcp stdio MCP helper and a local control socket path so external MCP clients can request that a running Architect instance spawn a new terminal session.
Changes:
- Introduces
architect-mcpMCP JSON-RPC server with a singlespawn_sessiontool and argument validation. - Adds an in-app Unix control socket listener + queue drained on the main loop to execute external spawn requests.
- Updates build/release packaging (macOS bundling, Homebrew, GitHub release workflow) and docs to ship and describe the helper.
Reviewed changes
Copilot reviewed 11 out of 11 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| src/mcp/main.zig | New MCP stdio server implementation + unit tests for tool listing and error results |
| src/app/runtime.zig | Main-loop drain/handling of external spawn requests; slot planning, cwd validation, command queueing; tests |
| src/app/control.zig | New shared control-socket protocol: discovery, request parsing, socket listener thread, request queue, response parsing |
| scripts/bundle-macos.sh | Bundles/signs architect-mcp into the app bundle and patches dylib references |
| docs/development.md | Notes that release archives include both architect and architect-mcp |
| docs/ai-integration.md | Documents MCP spawn_session interface and helper paths |
| docs/ARCHITECTURE.md | Updates architecture docs to include control socket + MCP helper data flow |
| build.zig | Builds/installs architect-mcp and adds a test target for it |
| README.md | Documents MCP capability, usage, and helper paths |
| Formula/architect.rb | Installs architect-mcp into the bundle and symlinks it on PATH |
| .github/workflows/release.yaml | Passes architect-mcp into the macOS bundling step |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Issue: Address PR #292 review comments about blocked control reads, shared discovery files, atomic discovery writes, and oversized MCP stdin lines. Solution: Bound local control request reads with a non-blocking accepted socket and a deadline, use per-user/per-process discovery files, atomically publish discovery JSON with 0600 permissions, and make the MCP stdin loop discard the rest of an oversized line before parsing again.
Issue: `architect-mcp` could miss the running app when Architect and the helper were launched from different environments, because the fallback discovery path used process-local TMPDIR values. Solution: Keep honoring XDG_RUNTIME_DIR when it is set, but otherwise use a stable per-user runtime directory under the user cache location. Create that managed directory with private permissions and document the discovery location so MCP clients can work without users copying temp paths.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Solution
Adds a separate
architect-mcpstdio helper for local MCP clients. It exposesspawn_session, validates the tool arguments, and forwards requests to the running Architect app through a Unix-domain control socket discovered from the runtime temp directory.The app handles those requests on the main loop: it validates the working directory, picks or expands a grid slot, spawns the terminal session, queues optional command text, focuses the new session, and returns structured success or stable error codes. Build, release packaging, Homebrew, and docs now ship and describe the helper.
Closes #291
Checks
nix develop -c zig buildnix develop -c zig build testnix develop -c just lintgit diff --checktools/listandspawn_sessionTest plan
spawn_sessionthrougharchitect-mcpwith an existing absolutecwd, and confirm a new focused session appears.spawn_sessionwith acommandvalue and confirm the command is submitted in the new shell.