Retulo: Keep Codex and Claude Code File Work Across Chats

Your agent finishes a report. You ask for two revisions, close the chat, and come back tomorrow.

Now there are three files. Which one used the latest source? Which checks still need to run? Did “done” mean the file was saved, reviewed, or actually sent?

Starting a new conversation should not mean reconstructing the file work from a chat transcript.

I'm sharing Retulo, an MIT-licensed Python CLI and MCP server that gives AI agents local workspaces for file-producing tasks. It keeps the task identity, source material, output versions, recorded decisions, remaining work, and checks together. It includes setup for Codex and Claude Code.

The current release is 0.5.0rc1, a preview. Here is what it does and how to try it.

Give the work an identity outside the chat

Retulo records a task with a UUID and a workspace path. The connected agent uses that record while creating or changing files.

The agent still interprets your request and runs its existing tools. Retulo manages the local records and file workflow; its core does not call models or launch agents.

Continuing in another chat requires identifying the actual task or workspace, with the same configuration and file access. Retulo does not guess which unrelated conversation you meant.

Install without a source checkout

On macOS or Linux:

curl -fsSL https://thestack-ai.github.io/retulo/install.sh | sh

Expect retulo 0.5.0rc1. The installer verifies the release wheel against its published SHA256SUMS, then installs it in a persistent uv tool environment. It uses an existing uv or installs a private copy, and obtains a suitable Python when needed. You do not need Git or a virtual environment to maintain yourself.

If the installer reports a missing command directory, run its printed PATH command. With the default location:

export PATH="$HOME/.local/bin:$PATH"

The preview is distributed through GitHub Releases. The installation guide includes script review and custom-path options.

Connect the client you already use

Install and sign in to Codex or Claude Code first. Replace the path below with an existing project directory. Setup previews changes by default; --apply writes them.

For Codex:

retulo setup codex --project /absolute/path/to/project
retulo setup codex --project /absolute/path/to/project --apply
retulo doctor codex --project /absolute/path/to/project --connect

For Claude Code:

retulo setup claude --project /absolute/path/to/project
retulo setup claude --project /absolute/path/to/project --apply
retulo doctor claude --project /absolute/path/to/project --connect

Setup adds the MCP connection and managed instructions, preserving unrelated settings and saving restoration snapshots. Existing code stays in its repository. The Codex integration also includes context hooks; Claude Code uses its project instructions.

Restart the client and start a new chat in the project. Review the client's project trust, hook trust, and MCP approval prompts as applicable. doctor --connect tests the configured server's MCP handshake and capabilities. The next step checks whether your agent actually follows the procedure.

Try one small file task

Ask your connected agent:

Use Retulo to create a Markdown welcome guide for this project.
Before writing, start the task and reserve the output.
Register the actual file, check its contents and integrity,
and report the task ID, workspace path, and output path.

Look for a real file, a task UUID, a workspace path, an artifact version, and actual check results. Open the guide yourself too: intact bytes do not establish good content.

Then request:

Add a contact section to that guide. Keep the earlier version
and record fresh checks.

For the continuation test, copy the actual UUID and workspace path returned by your agent. Open a new conversation with the same Retulo configuration and file access, substitute those values below, and ask:

Continue Retulo task TASK_UUID in WORKSPACE_PATH.
Read its recorded state first, then add an opening-hours section.
Keep the previous versions.

The task ID and workspace should stay the same, with another recorded output version. Once you confirm this works, the installed guidance can apply the procedure to ordinary file requests without naming Retulo every time.

Update a workflow or reuse its recipe

For a report with several production steps, a changed input can affect only part of the work. Retulo records explicit relationships between inputs, steps, and exact output versions. Its rebuild planner identifies affected steps and checks whether eligible, unchanged steps can be reused.

Those dependencies must be declared. Retulo does not intercept every file a tool reads. The host agent executes the producers against fixed input snapshots and reserved output paths.

A recipe saves the workflow and typed input contract for a new task. “Update this report” keeps the existing task identity; “use this process with next month's data” starts fresh work with fresh checks. Previous approvals do not carry over. The workflow documentation explains the contract and runnable example.

Preview scope and feedback

macOS with a local filesystem is the tested local environment. Release verification includes 435 tests, MCP SDK checks, native client CLI checks, and a successful macOS/Linux CI matrix covering Python 3.11 and 3.14. Transport checks and deterministic continuity examples do not establish fully automatic adoption by a fresh agent conversation; try the guide task in your own client.

Managed settings operations stop when they detect conflicting edits rather than overwriting them. Disconnecting preserves task workspaces, artifacts, and the core Retulo configuration. See the documentation for setup and recovery details.

If your AI work ends in files, try the welcome-guide task. Tell me where continuing the work still feels awkward, or open a reproducible GitHub issue. That feedback will help shape the next release.

Disclosure: This article was drafted and checked by AI agents against Retulo’s source, release files, and validation records.