[codex] Add agent review CLI and review API

[iheanyi]

Summary

Pivots the agentic review integration from a long-lived MCP server to a lightweight tuicr review CLI, following the maintainer suggestion in the latest review discussion.

• Adds tuicr review open --repo . --diff-source working-tree --json.
• Adds tuicr review diff --session <id> --path <path> --max-lines <n>.
• Adds tuicr review comment add --session <id> --path <path> --line <n> --side new --type issue --body "...".
• Adds tuicr review file reviewed --session <id> --path <path> --set true.
• Adds tuicr review export --session <id> and tuicr review clear --session <id>.
• Keeps tuicr::review_api::ReviewService as the public Rust API for external integrations.
• Removes the MCP protocol/server adapter and drops the rmcp/tokio dependency additions.
• Persists CLI-opened sessions and reloads them by session id across separate CLI invocations.

Design

The CLI is now the first-party agent integration surface. It uses the same shared review service as the public Rust API, so an external tuicr-mcp or app package can either depend on the crate API or wrap the CLI without adding a protocol server to this repository.

The persisted-session reload path preserves the originally opened file set. For example, opening a narrow review with --path src/review_cli.rs keeps later diff, comment, export, and clear commands scoped to that same loaded review instead of expanding to the full working tree.

Validation

• cargo fmt
• cargo check
• cargo test review_cli
• cargo test
• CLI smoke against this branch:
  • target/debug/tuicr review open --repo . --diff-source working-tree --path src/review_cli.rs --json
  • target/debug/tuicr review diff --session <id> --path src/review_cli.rs --max-lines 12
  • target/debug/tuicr review comment add --session <id> --path src/review_cli.rs --line 2 --side new --type note --body "..."
  • target/debug/tuicr review file reviewed --session <id> --path src/review_cli.rs --set true
  • target/debug/tuicr review export --session <id>
  • target/debug/tuicr review clear --session <id>

[agavra]

Hey @iheanyi - I'm not especially eager to ship tuicr with a server side component, I'd rather keep it a simple CLI tool. There's been some discussion on this in the past (see #221). There are quite a few diff tools that ship with a frontend that are pretty good if you want to check those out.

[iheanyi]

@agavra What if we wrote it in Rust to plug into the current CLI? I use Codex's CLI at work and the Codex desktop app at home and I'd like to be able to use Tuicr from the Codex app without breaking flow-state. With an MCP app, I can do the code review in my application and also paste it directly back into the desktop app, could you let me know your concerns about adding MCP App Support per chance?

[agavra]

adding node/javascript dependencies is definitely a concern with all of the recent supply chain vulnerabilities. Rust isn't immune from that but it's at least slightly better.

In general this would add a lot of surface area for tuicr, which means more potential "weird" interactions and a higher test burden. For now I've been testing most PRs manually, adding a server (and especially a frontend) adds a component that is quite a bit tougher to verify.

But I admit I don't totally understand your workflow because I don't use the Codex or Claude apps myself, what is the workflow problem you're trying to solve? Is running a terminal window and then copying from that into the Codex app no good?

[iheanyi]

I hear you on that and that's a fair concern with all of the supply chain risks these days.

That's pretty much it, I don't like context switching in tools I use, personally. When I'm in the terminal, I use tmux and the like. I guess I could do it from a terminal and copy and paste it in there, but having it streamlined would've been nice as well. For MCP apps, it interfaces with Claude and Codex similarly to the CLI review skill itself And can directly send feedback back into the chat interface, so it's the same as my cli flow with tmux.

[agavra]

Got it, you are the second person to request MCP support so it might be worth designing something for that. I'm pretty firm on the "no frontend" outside of a TUI line, but I can be open to a minimal rust server that implements the MCP protocol for shipping feeback to an agent.

[iheanyi]

Still working on the MCP Server, but I was able to record a video of the MCP App flow for posterity at least, as you can see, it makes it a lot more streamlined and all of that for addressing review comments and loading them back up and in tandem with MCP itself, it could be published right back into the application itself.

CleanShot.2026-05-12.at.22.24.06.mp4

[iheanyi]

@agavra This is ready for review. As a middleground, I exposed the ReviewService as a public crate. Idea is that we can keep the tuicr-app out of this repository, but I can make a separate repository for tuicr-app that adds the desired MCP UI/App functionality for folks who want it, that way we get the best of both worlds and this one stays CLI-only.

[agavra]

thanks @iheanyi - I'm getting excited about this change, I'll need to set aside some time to review and test it so may not get around to it immediately but it's on my radar

[agavra]

Thanks @iheanyi for the back and forth on this.

I spent some time playing around with this and reviewing it and I'm back to being unconvinced we need this. An alternative if we want a native interaction with agents would be to expose a CLI with the following commands:

  tuicr review open --repo . --diff-source working-tree --json
  tuicr review diff --session <id> --path src/main.rs --max-lines 200
  tuicr review comment add --session <id> --path src/main.rs --line 42 --side new --type issue --body "..."
  tuicr review file reviewed --session <id> --path src/main.rs --set true
  tuicr review export --session <id>
  tuicr review clear --session <id>

That way the agent can use the tuicr CLI to interact with a tuicr JSON storage file. We can have tuicr hot-reload the contents of that file so that it's interactive both ways.

The CLI has various benefits (here's what codex says):

---

The core workflow seems to be: let an agent inspect the active review, add comments, mark files reviewed, and export the final review. A small CLI that mutates tuicr’s existing session files through the same Rust validation code could support that without introducing a long-lived server/protocol surface.

• Simpler security model: each operation is an explicit process invocation instead of a persistent MCP capability exposed to agents.
• Easier to audit and debug: commands, args, stdout/stderr, and exit codes are visible and reproducible.
• Better alignment with tuicr’s current persistence model: agents can update the same review session files the TUI already uses.
• The TUI could hot-reload the active session when the file changes, allowing human and agent edits to meet in the same place.
• Less protocol-specific maintenance: no MCP schemas, session server lifecycle, or client compatibility concerns.
• Reusable outside MCP-aware clients: any agent or script can call a CLI.
• Easier testing: command-level integration tests can assert file mutations, validation errors, and export output.

---

That said, I don't mind the refactor into a library (I actively like it) where you could then write a tuicr-mcp using the published cargo crates as a dependency if the MCP is something you absolutely need. Alternatively, you can build an MCP server around the CLI directly.

I admit I never use MCPs over CLIs, and I'm pretty stuck in the TUIs for Claude/Codex. Maybe I'll start playing around more with the desktop apps eventually and then understand the need.

[iheanyi]

Addressed the CLI pivot suggested above.

What changed:

• Removed the MCP server/protocol adapter from this PR.
• Dropped the added rmcp and tokio dependencies.
• Kept the public tuicr::review_api::ReviewService surface.
• Added the proposed tuicr review ... command family over the same review service:
  • open
  • diff
  • comment add
  • file reviewed
  • export
  • clear
• Added session-id reload support so separate CLI invocations can keep working against the same persisted review.

Validation:

• cargo fmt
• cargo check
• cargo test review_cli
• cargo test
• Manual CLI smoke against this branch for open, diff, comment add, file reviewed, export, and clear.

One behavior I tightened while smoke-testing: if a review is opened with a file/path filter, later commands by --session now preserve that originally loaded file set instead of expanding to the whole working tree.

[agavra]

@iheanyi I think you told me you have a bot that addresses review comments automatically, so i just want to make sure you (the human) are OK with this new approach.

[iheanyi]

@agavra Yeah, haha, that's cool with me. I had read it yesterday before bed and forgot to respond, oops.

[iheanyi]

I do like having it exposed as a CLI in this case at least. And having tuicr-mcp separately also makes sense, can encapsulate both the MCP itself and the MCP App too, good call

[agavra]

@iheanyi if you don't mind, now that we've agreed on an approach, I'm going to take this feature on. I think it's a pretty critical core feature to tuicr UX and I'd like to do a proper design exercise and think through how it works.

I spent a little time reviewing codex's approach to it and I'm not super thrilled. I'll try to get it going tonight so it can unblock your agent-driven review workflow.

[agavra]

#310

[iheanyi]

That's perfectly fine @agavra! All I request is that make sure the service is exported/public so I can use it in a crate!