MallardDocs

Introduction

Sync Codex knowledge with the project.

Mallard lets you choose the Codex sessions and reusable setup that should follow a project to another machine. Your source repository stays where it is.

The problem Mallard solvesProject-specific conversations, decisions, skills, and setup usually stay on one laptop. Mallard packages only the pieces you approve so another host or teammate can restore them deliberately.
Mallard syncs selected Codex project context through a local folder or R2 to another host.
Review what moves. Verify what arrives. Approve before restore.
Moves when selectedCodex conversations, project instructions, skills, plugins, tools, hooks, and supported settings.
Stays on this machineThe source checkout, credentials, authentication state, absolute paths, backups, and restore approval.

Getting started · 1

Configure Project

Start with the folder Codex already uses. Mallard uses that checkout to discover the conversations and project files that belong together.

  1. 1
    Choose the project folder

    Select the existing checkout on this machine. Git helps Mallard match the same repository on another host, but a non-Git folder also works.

  2. 2
    Choose the Codex profile

    Select the exact Codex home used for this project—normally ~/.codex, or a custom CODEX_HOME. Mallard reads project-related resources from this profile.

  3. 3
    Name the project

    Use a name teammates will recognize. If you connect an existing remote repository, Mallard adopts its shared name and identity.

Machine-local bindingThe checkout path and Codex home belong to this machine. Absolute paths are never uploaded, so the next host can map its own folders safely.

Getting started · 1.1

Review Git-based Projects

A Git project gives Mallard enough structure to show not only which Codex sessions happened, but where they fit in the work. The activity page combines the selected branch, its first-parent commit history, and the sessions detected for the project so a developer can move from a code change to the reasoning behind it without searching through a separate chat archive.

Use the Branch menu when you want to review another line of work. Sessions recorded on that branch appear beside the commits they relate to, while Uncommitted Changes keeps sessions that are not linked to a commit in the selected branch visible at the top. This makes unfinished investigations easy to find and prevents useful work from disappearing simply because it has not produced a commit yet. The commit rail shows the short SHA, date, and commit subject, giving reviewers and returning developers a chronological explanation layer over the repository history.

Project activitymallard-desktop
Branchmain · current
Uncommitted ChangesSessions not linked to a commit in this branch
Investigate restore conflict handling
↗ Open in Codex⌘ Open in Terminal
Started · Jul 19, 9:14 AMEnded · Jul 19, 10:02 AM
User rounds 6Total tokens 84.2KAgent messages 18Tool calls 11
› Show chat details
Commit history2 sessions · 2 commit occurrences
  1. a42d91eJul 19, 10:18 AMGuard restore plan conflicts
    Verify restore safeguards
    ↗ Open in Codex⌘ Open in Terminal
    User rounds 3Total tokens 46.8KAgent messages 9Tool calls 7
    › Show chat details

Every session card summarizes its start and end time, User rounds, Total tokens, Agent messages, and Tool calls. Those signals help you distinguish a quick question from a deep implementation session, estimate where the team invested attention, and choose the right conversation before opening it. Show chat details expands a readable preview of the user and Codex turns for a quick check. When you need the full working context, Open in Codex opens that exact session in the Codex desktop app, while Open in Terminal resumes it with the Codex CLI in the project checkout. These one-click handoffs turn the activity view into a practical starting point for code review, onboarding, debugging, and continuing work after a handoff.

History is branch-awareA session recorded on another named branch is not placed on the selected branch’s commit rail. Older sessions without branch metadata may appear as a best-effort match, and deleted recorded branches remain visible as unavailable so their history is not silently lost.

Getting started · 1.2

Review Non-Git Projects

Mallard does not require a Git repository to make Codex work discoverable. For prototypes, research folders, scripts, and projects that have not entered version control, the activity page gathers project-owned Codex threads into one timeline ordered by last activity. You still get the context needed to understand what happened in the folder, without inventing commit relationships that do not exist.

The project summary identifies the local directory, bound Codex profile, and latest Push or Pull for each linked storage target. Below it, Codex threads presents the newest work first. Each card uses the same session title, dates, User rounds, Total tokens, Agent messages, Tool calls, chat preview, and launch actions as a Git project. The difference is deliberately simple: without commits or branches, Mallard organizes work by recency so the next useful session is usually at the top.

Project activityapi-spike
↻ Refresh
Directory~/Projects/api-spikeCodex configuration~/.codexStorage syncTeam folder · Push today
Codex threadsOrdered by last activity
Compare authentication approaches
↗ Open in Codex⌘ Open in Terminal
Started · Jul 20, 8:42 AMLast activity · Jul 20, 9:26 AM
User rounds 5Total tokens 61.4KAgent messages 14Tool calls 8
› Show chat details
Sketch the first API client
↗ Open in Codex⌘ Open in Terminal
User rounds 2Total tokens 28.9KAgent messages 7Tool calls 5
› Show chat details

This view is especially useful before a project has a formal repository: a developer can recover the decisions behind an experiment, inspect how much iteration a thread required, and continue the exact task instead of reconstructing the prompt from memory. If the folder later becomes a Git repository, future activity can use branch and commit context; the non-Git view remains an honest record of the earlier work. Like Git projects, activity is discovered from the Codex profile bound to this project, and Mallard can load previous 30-day windows when you need older sessions.

Same developer context, simpler orderingNon-Git projects retain the session-level value—summaries, details, metrics, storage status, and one-click resume actions—while leaving out branch and commit controls that would not be meaningful.

Getting started · 2

Configure Storage

Storage is the meeting point between hosts. Use a local folder for a simple shared location, or Cloudflare R2 for remote object storage you control.

Local folder

Point Mallard at a directory

Choose a folder on a shared drive, synced folder, removable disk, or another path both workflows can reach. Mallard writes versioned project data inside it.

/Volumes/team/mallard-storage
Cloudflare R2

Connect one bucket

Create a bucket and an Object Read & Write token scoped to that bucket. Enter the S3 API URL, bucket name, Account ID, Access Key ID, and Secret Access Key. Mallard uses region auto.

Credentials stay localEach host configures its own storage credentials. They are not included in project bundles.

Getting started · 3

Select Artifacts

Mallard discovers resources related to the chosen checkout and Codex profile. Review the list and save the selection as the project’s portable recipe.

ConversationsProject tasks, sessions, memory, and filtered indexes.
Project setupInstructions and supported project configuration.
SkillsProject skills and the standalone skills you choose.
PluginsPortable install intent—not plugin payloads or caches.
Tools & hooksMCP servers, hooks, commands, and environment requirements.

Mallard may ask you to review the list again when the profile changes or new resources appear. Nothing outside the saved recipe is pushed.

Getting started · 4

Push and Pull

Push publishes a reviewed generation. Pull fetches and verifies that generation, then pauses for review before changing the destination host.

A

On the source host

  1. Open the project and select a storage target.
  2. Review local changes and the saved resource recipe.
  3. Choose Push project, or Finish & push during setup.
  4. Wait for the generation to finish before closing Mallard.
B

On the destination host

  1. Check out the same source project and configure the Codex home used there.
  2. Add the same storage and connect the matching remote repository.
  3. Choose Pull & review. Mallard fetches the generation and verifies its manifest and content hashes.
  4. Inspect the restore plan, resolve any conflicts or blocked items, then explicitly approve Apply.
Review does not apply changesFetch, verification, and restore planning are separate from the final apply step. Backups and conflict handling remain local to the destination machine.

Configuration settings

Project Settings

A project combines a shared repository identity with a machine-local checkout and Codex profile.

Project name
The shared label used to recognize the project in Mallard and storage.
Project checkout
The local folder that anchors project-relative discovery. Another host can use a different absolute path.
Codex profile
The local Codex home used for discovery and restore. Change the machine-local binding if this host uses a different profile.
Resource recipe
The saved set of conversations, setup, skills, plugins, and tools that Push may include.
Storage links
One project can link to multiple storage targets. Every link keeps its own reviewed base and sync history.

Configuration settings

Storage Settings

Storage definitions are local to Mallard on this host. Give each one a clear name so you know where a project is being pushed.

Local folderName and location path.
Cloudflare R2Name, S3 API URL, bucket, Account ID, Access Key ID, Secret Access Key, and region auto.

Changing a storage connection changes where future Push and Pull operations look. Unlink the storage from a project before adopting a different remote repository identity.

Removing storage is non-destructiveRemoving or unlinking a storage entry does not delete stored files or remote generations. It removes Mallard’s local connection to that location.

Configuration settings

Removing a Project

Remove a project when this Mallard installation should stop tracking it.

RemovedMallard’s local project registration and active storage links on this host.
Not removedThe checkout, Codex files, backups, or any bundles already written to local or cloud storage.

Removing a project does not delete project files. It detaches Mallard’s machine-local binding so the same project can be mapped again later.

Troubleshooting

Troubleshooting and Sync Logs

Use Sync Logs to answer three questions quickly: what Mallard tried, where it stopped, and what you can do next.

Filter by activityPush, Pull, Repair, Storage, Configuration, History, and System.
Filter by levelInfo, Success, Warning, and Error.
Find an eventSearch the message text and load older retained entries.
Inspect locallyOpen ~/.mallard/logs to see the structured JSONL files.

A practical triage order

  1. Filter to the failed action. Start with Push or Pull, then include Storage or Configuration if the failure happened before transfer.
  2. Read the first warning or error. Later messages often describe cleanup after the original cause.
  3. Confirm project and storage names. Log entries carry local project and storage context without uploading the log history.
  4. Retry after correcting the setting. A new run remains separate, making it easier to compare outcomes.

Manage retained logs

Logs stay on this machine. The default policy keeps them for 30 days with a maximum of 100 MB. In Manage logs, you can change both limits, open the folder, clean up old files, or delete all retained activity logs.

Log cleanup is isolatedCleanup never removes sync state, backups, local files, or cloud generations. If log persistence is unavailable, current entries can still remain visible until Mallard closes.
Ready to try the flow?
Check platform availabilityView the Roadmap