feat(tui/git-tooling): add workspace snapshot undo flow

codex-rs/Cargo.lock

@@ -1073,6 +1073,16 @@ dependencies = [
  "tokio",
 ]
 
+[[package]]
+name = "codex-git-tooling"
+version = "0.0.0"
+dependencies = [
+ "pretty_assertions",
+ "tempfile",
+ "thiserror 2.0.16",
+ "walkdir",
+]
+
 [[package]]
 name = "codex-linux-sandbox"
 version = "0.0.0"
@@ -1215,6 +1225,7 @@ dependencies = [
  "codex-common",
  "codex-core",
  "codex-file-search",
+ "codex-git-tooling",
  "codex-login",
  "codex-ollama",
  "codex-protocol",

codex-rs/Cargo.toml

@@ -9,6 +9,7 @@ members = [
     "exec",
     "execpolicy",
     "file-search",
+    "git-tooling",
     "linux-sandbox",
     "login",
     "mcp-client",
@@ -39,6 +40,7 @@ codex-common = { path = "common" }
 codex-core = { path = "core" }
 codex-exec = { path = "exec" }
 codex-file-search = { path = "file-search" }
+codex-git-tooling = { path = "git-tooling" }
 codex-linux-sandbox = { path = "linux-sandbox" }
 codex-login = { path = "login" }
 codex-mcp-client = { path = "mcp-client" }

codex-rs/git-tooling/Cargo.toml

@@ -0,0 +1,20 @@
+[package]
+name = "codex-git-tooling"
+version.workspace = true
+edition.workspace = true
+readme = "README.md"
+
+[lib]
+name = "codex_git_tooling"
+path = "src/lib.rs"
+
+[dependencies]
+tempfile = "3"
+thiserror = "2"
+walkdir = "2"
+
+[lints]
+workspace = true
+
+[dev-dependencies]
+pretty_assertions = "1.4.1"

codex-rs/git-tooling/README.md

@@ -0,0 +1,21 @@
+# codex-git-tooling
+
+Helpers for interacting with git, primarily used by Code to capture and restore
+workspace snapshots.
+
+```rust,no_run
+use std::path::Path;
+
+use codex_git_tooling::{create_ghost_commit, restore_ghost_commit, CreateGhostCommitOptions};
+
+let repo = Path::new("/path/to/repo");
+
+// Capture the current working tree as an unreferenced commit.
+let ghost = create_ghost_commit(&CreateGhostCommitOptions::new(repo))?;
+
+// Later, roll back to that state.
+restore_ghost_commit(repo, &ghost)?;
+```
+
+Pass a custom message with `.message("…")` or force-include ignored files with
+`.force_include(["ignored.log".into()])`.

codex-rs/git-tooling/src/errors.rs

@@ -0,0 +1,35 @@
+use std::path::PathBuf;
+use std::process::ExitStatus;
+use std::string::FromUtf8Error;
+
+use thiserror::Error;
+use walkdir::Error as WalkdirError;
+
+/// Errors returned while managing git worktree snapshots.
+#[derive(Debug, Error)]
+pub enum GitToolingError {
+    #[error("git command `{command}` failed with status {status}: {stderr}")]
+    GitCommand {
+        command: String,
+        status: ExitStatus,
+        stderr: String,
+    },
+    #[error("git command `{command}` produced non-UTF-8 output")]
+    GitOutputUtf8 {
+        command: String,
+        #[source]
+        source: FromUtf8Error,
+    },
+    #[error("{path:?} is not a git repository")]
+    NotAGitRepository { path: PathBuf },
+    #[error("path {path:?} must be relative to the repository root")]
+    NonRelativePath { path: PathBuf },
+    #[error("path {path:?} escapes the repository root")]
+    PathEscapesRepository { path: PathBuf },
+    #[error("failed to process path inside worktree")]
+    PathPrefix(#[from] std::path::StripPrefixError),
+    #[error(transparent)]
+    Walkdir(#[from] WalkdirError),
+    #[error(transparent)]
+    Io(#[from] std::io::Error),
+}

codex-rs/git-tooling/src/ghost_commits.rs

@@ -0,0 +1,494 @@
+use std::ffi::OsString;
+use std::path::Path;
+use std::path::PathBuf;
+
+use tempfile::Builder;
+
+use crate::GhostCommit;
+use crate::GitToolingError;
+use crate::operations::apply_repo_prefix_to_force_include;
+use crate::operations::ensure_git_repository;
+use crate::operations::normalize_relative_path;
+use crate::operations::repo_subdir;
+use crate::operations::resolve_head;
+use crate::operations::resolve_repository_root;
+use crate::operations::run_git_for_status;
+use crate::operations::run_git_for_stdout;
+
+/// Default commit message used for ghost commits when none is provided.
+const DEFAULT_COMMIT_MESSAGE: &str = "code snapshot";
+
+/// Options to control ghost commit creation.
+pub struct CreateGhostCommitOptions<'a> {
+    pub repo_path: &'a Path,
+    pub message: Option<&'a str>,
+    pub force_include: Vec<PathBuf>,
+}
+
+impl<'a> CreateGhostCommitOptions<'a> {
+    /// Creates options scoped to the provided repository path.
+    pub fn new(repo_path: &'a Path) -> Self {
+        Self {
+            repo_path,
+            message: None,
+            force_include: Vec::new(),
+        }
+    }
+
+    /// Sets a custom commit message for the ghost commit.
+    pub fn message(mut self, message: &'a str) -> Self {
+        self.message = Some(message);
+        self
+    }
+
+    /// Supplies the entire force-include path list at once.
+    pub fn force_include<I>(mut self, paths: I) -> Self
+    where
+        I: IntoIterator<Item = PathBuf>,
+    {
+        self.force_include = paths.into_iter().collect();
+        self
+    }
+
+    /// Adds a single path to the force-include list.
+    pub fn push_force_include<P>(mut self, path: P) -> Self
+    where
+        P: Into<PathBuf>,
+    {
+        self.force_include.push(path.into());
+        self
+    }
+}
+
+/// Create a ghost commit capturing the current state of the repository's working tree.
+pub fn create_ghost_commit(
+    options: &CreateGhostCommitOptions<'_>,
+) -> Result<GhostCommit, GitToolingError> {
+    ensure_git_repository(options.repo_path)?;
+
+    let repo_root = resolve_repository_root(options.repo_path)?;
+    let repo_prefix = repo_subdir(repo_root.as_path(), options.repo_path);
+    let parent = resolve_head(repo_root.as_path())?;
+
+    let normalized_force = options
+        .force_include
+        .iter()
+        .map(|path| normalize_relative_path(path))
+        .collect::<Result<Vec<_>, _>>()?;
+    let force_include =
+        apply_repo_prefix_to_force_include(repo_prefix.as_deref(), &normalized_force);
+    let index_tempdir = Builder::new().prefix("code-git-index-").tempdir()?;
+    let index_path = index_tempdir.path().join("index");
+    let base_env = vec![(
+        OsString::from("GIT_INDEX_FILE"),
+        OsString::from(index_path.as_os_str()),
+    )];
+
+    let mut add_args = vec![OsString::from("add"), OsString::from("--all")];
+    if let Some(prefix) = repo_prefix.as_deref() {
+        add_args.extend([OsString::from("--"), prefix.as_os_str().to_os_string()]);
+    }
+
+    run_git_for_status(repo_root.as_path(), add_args, Some(base_env.as_slice()))?;
+    if !force_include.is_empty() {
+        let mut args = Vec::with_capacity(force_include.len() + 2);
+        args.push(OsString::from("add"));
+        args.push(OsString::from("--force"));
+        args.extend(
+            force_include
+                .iter()
+                .map(|path| OsString::from(path.as_os_str())),
+        );
+        run_git_for_status(repo_root.as_path(), args, Some(base_env.as_slice()))?;
+    }
+
+    let tree_id = run_git_for_stdout(
+        repo_root.as_path(),
+        vec![OsString::from("write-tree")],
+        Some(base_env.as_slice()),
+    )?;
+
+    let mut commit_env = base_env;
+    commit_env.extend(default_commit_identity());
+    let message = options.message.unwrap_or(DEFAULT_COMMIT_MESSAGE);
+    let commit_args = {
+        let mut result = vec![OsString::from("commit-tree"), OsString::from(&tree_id)];
+        if let Some(parent) = parent.as_deref() {
+            result.extend([OsString::from("-p"), OsString::from(parent)]);
+        }
+        result.extend([OsString::from("-m"), OsString::from(message)]);
+        result
+    };
+
+    // Retrieve commit ID.
+    let commit_id = run_git_for_stdout(
+        repo_root.as_path(),
+        commit_args,
+        Some(commit_env.as_slice()),
+    )?;
+
+    Ok(GhostCommit::new(commit_id, parent))
+}
+
+/// Restore the working tree to match the provided ghost commit.
+pub fn restore_ghost_commit(repo_path: &Path, commit: &GhostCommit) -> Result<(), GitToolingError> {
+    restore_to_commit(repo_path, commit.id())
+}
+
+/// Restore the working tree to match the given commit ID.
+pub fn restore_to_commit(repo_path: &Path, commit_id: &str) -> Result<(), GitToolingError> {
+    ensure_git_repository(repo_path)?;
+
+    let repo_root = resolve_repository_root(repo_path)?;
+    let repo_prefix = repo_subdir(repo_root.as_path(), repo_path);
+
+    let mut restore_args = vec![
+        OsString::from("restore"),
+        OsString::from("--source"),
+        OsString::from(commit_id),
+        OsString::from("--worktree"),
+        OsString::from("--staged"),
+        OsString::from("--"),
+    ];
+    if let Some(prefix) = repo_prefix.as_deref() {
+        restore_args.push(prefix.as_os_str().to_os_string());
+    } else {
+        restore_args.push(OsString::from("."));
+    }
+
+    run_git_for_status(repo_root.as_path(), restore_args, None)?;
+    Ok(())
+}
+
+/// Returns the default author and committer identity for ghost commits.
+fn default_commit_identity() -> Vec<(OsString, OsString)> {
+    vec![
+        (
+            OsString::from("GIT_AUTHOR_NAME"),
+            OsString::from("Code Snapshot"),
+        ),
+        (
+            OsString::from("GIT_AUTHOR_EMAIL"),
+            OsString::from("[email protected]"),
+        ),
+        (
+            OsString::from("GIT_COMMITTER_NAME"),
+            OsString::from("Code Snapshot"),
+        ),
+        (
+            OsString::from("GIT_COMMITTER_EMAIL"),
+            OsString::from("[email protected]"),
+        ),
+    ]
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::operations::run_git_for_stdout;
+    use pretty_assertions::assert_eq;
+    use std::process::Command;
+
+    /// Runs a git command in the test repository and asserts success.
+    fn run_git_in(repo_path: &Path, args: &[&str]) {
+        let status = Command::new("git")
+            .current_dir(repo_path)
+            .args(args)
+            .status()
+            .expect("git command");
+        assert!(status.success(), "git command failed: {args:?}");
+    }
+
+    /// Runs a git command and returns its trimmed stdout output.
+    fn run_git_stdout(repo_path: &Path, args: &[&str]) -> String {
+        let output = Command::new("git")
+            .current_dir(repo_path)
+            .args(args)
+            .output()
+            .expect("git command");
+        assert!(output.status.success(), "git command failed: {args:?}");
+        String::from_utf8_lossy(&output.stdout).trim().to_string()
+    }
+
+    /// Initializes a repository with consistent settings for cross-platform tests.
+    fn init_test_repo(repo: &Path) {
+        run_git_in(repo, &["init", "--initial-branch=main"]);
+        run_git_in(repo, &["config", "core.autocrlf", "false"]);
+    }
+
+    #[test]
+    /// Verifies a ghost commit can be created and restored end to end.
+    fn create_and_restore_roundtrip() -> Result<(), GitToolingError> {
+        let temp = tempfile::tempdir()?;
+        let repo = temp.path();
+        init_test_repo(repo);
+        std::fs::write(repo.join("tracked.txt"), "initial\n")?;
+        std::fs::write(repo.join("delete-me.txt"), "to be removed\n")?;
+        run_git_in(repo, &["add", "tracked.txt", "delete-me.txt"]);
+        run_git_in(
+            repo,
+            &[
+                "-c",
+                "user.name=Tester",
+                "-c",
+                "[email protected]",
+                "commit",
+                "-m",
+                "init",
+            ],
+        );
+
+        let tracked_contents = "modified contents\n";
+        std::fs::write(repo.join("tracked.txt"), tracked_contents)?;
+        std::fs::remove_file(repo.join("delete-me.txt"))?;
+        let new_file_contents = "hello ghost\n";
+        std::fs::write(repo.join("new-file.txt"), new_file_contents)?;
+        std::fs::write(repo.join(".gitignore"), "ignored.txt\n")?;
+        let ignored_contents = "ignored but captured\n";
+        std::fs::write(repo.join("ignored.txt"), ignored_contents)?;
+
+        let options =
+            CreateGhostCommitOptions::new(repo).force_include(vec![PathBuf::from("ignored.txt")]);
+        let ghost = create_ghost_commit(&options)?;
+
+        assert!(ghost.parent().is_some());
+        let cat = run_git_for_stdout(
+            repo,
+            vec![
+                OsString::from("show"),
+                OsString::from(format!("{}:ignored.txt", ghost.id())),
+            ],
+            None,
+        )?;
+        assert_eq!(cat, ignored_contents.trim());
+
+        std::fs::write(repo.join("tracked.txt"), "other state\n")?;
+        std::fs::write(repo.join("ignored.txt"), "changed\n")?;
+        std::fs::remove_file(repo.join("new-file.txt"))?;
+        std::fs::write(repo.join("ephemeral.txt"), "temp data\n")?;
+
+        restore_ghost_commit(repo, &ghost)?;
+
+        let tracked_after = std::fs::read_to_string(repo.join("tracked.txt"))?;
+        assert_eq!(tracked_after, tracked_contents);
+        let ignored_after = std::fs::read_to_string(repo.join("ignored.txt"))?;
+        assert_eq!(ignored_after, ignored_contents);
+        let new_file_after = std::fs::read_to_string(repo.join("new-file.txt"))?;
+        assert_eq!(new_file_after, new_file_contents);
+        assert_eq!(repo.join("delete-me.txt").exists(), false);
+        assert!(repo.join("ephemeral.txt").exists());
+
+        Ok(())
+    }
+
+    #[test]
+    /// Ensures ghost commits succeed in repositories without an existing HEAD.
+    fn create_snapshot_without_existing_head() -> Result<(), GitToolingError> {
+        let temp = tempfile::tempdir()?;
+        let repo = temp.path();
+        init_test_repo(repo);
+
+        let tracked_contents = "first contents\n";
+        std::fs::write(repo.join("tracked.txt"), tracked_contents)?;
+        let ignored_contents = "ignored but captured\n";
+        std::fs::write(repo.join(".gitignore"), "ignored.txt\n")?;
+        std::fs::write(repo.join("ignored.txt"), ignored_contents)?;
+
+        let options =
+            CreateGhostCommitOptions::new(repo).force_include(vec![PathBuf::from("ignored.txt")]);
+        let ghost = create_ghost_commit(&options)?;
+
+        assert!(ghost.parent().is_none());
+
+        let message = run_git_stdout(repo, &["log", "-1", "--format=%s", ghost.id()]);
+        assert_eq!(message, DEFAULT_COMMIT_MESSAGE);
+
+        let ignored = run_git_stdout(repo, &["show", &format!("{}:ignored.txt", ghost.id())]);
+        assert_eq!(ignored, ignored_contents.trim());
+
+        Ok(())
+    }
+
+    #[test]
+    /// Confirms custom messages are used when creating ghost commits.
+    fn create_ghost_commit_uses_custom_message() -> Result<(), GitToolingError> {
+        let temp = tempfile::tempdir()?;
+        let repo = temp.path();
+        init_test_repo(repo);
+
+        std::fs::write(repo.join("tracked.txt"), "contents\n")?;
+        run_git_in(repo, &["add", "tracked.txt"]);
+        run_git_in(
+            repo,
+            &[
+                "-c",
+                "user.name=Tester",
+                "-c",
+                "[email protected]",
+                "commit",
+                "-m",
+                "initial",
+            ],
+        );
+
+        let message = "custom message";
+        let ghost = create_ghost_commit(&CreateGhostCommitOptions::new(repo).message(message))?;
+        let commit_message = run_git_stdout(repo, &["log", "-1", "--format=%s", ghost.id()]);
+        assert_eq!(commit_message, message);
+
+        Ok(())
+    }
+
+    #[test]
+    /// Rejects force-included paths that escape the repository.
+    fn create_ghost_commit_rejects_force_include_parent_path() {
+        let temp = tempfile::tempdir().expect("tempdir");
+        let repo = temp.path();
+        init_test_repo(repo);
+        let options = CreateGhostCommitOptions::new(repo)
+            .force_include(vec![PathBuf::from("../outside.txt")]);
+        let err = create_ghost_commit(&options).unwrap_err();
+        assert!(matches!(err, GitToolingError::PathEscapesRepository { .. }));
+    }
+
+    #[test]
+    /// Restoring a ghost commit from a non-git directory fails.
+    fn restore_requires_git_repository() {
+        let temp = tempfile::tempdir().expect("tempdir");
+        let err = restore_to_commit(temp.path(), "deadbeef").unwrap_err();
+        assert!(matches!(err, GitToolingError::NotAGitRepository { .. }));
+    }
+
+    #[test]
+    /// Restoring from a subdirectory affects only that subdirectory.
+    fn restore_from_subdirectory_restores_files_relatively() -> Result<(), GitToolingError> {
+        let temp = tempfile::tempdir()?;
+        let repo = temp.path();
+        init_test_repo(repo);
+
+        std::fs::create_dir_all(repo.join("workspace"))?;
+        let workspace = repo.join("workspace");
+        std::fs::write(repo.join("root.txt"), "root contents\n")?;
+        std::fs::write(workspace.join("nested.txt"), "nested contents\n")?;
+        run_git_in(repo, &["add", "."]);
+        run_git_in(
+            repo,
+            &[
+                "-c",
+                "user.name=Tester",
+                "-c",
+                "[email protected]",
+                "commit",
+                "-m",
+                "initial",
+            ],
+        );
+
+        std::fs::write(repo.join("root.txt"), "root modified\n")?;
+        std::fs::write(workspace.join("nested.txt"), "nested modified\n")?;
+
+        let ghost = create_ghost_commit(&CreateGhostCommitOptions::new(&workspace))?;
+
+        std::fs::write(repo.join("root.txt"), "root after\n")?;
+        std::fs::write(workspace.join("nested.txt"), "nested after\n")?;
+
+        restore_ghost_commit(&workspace, &ghost)?;
+
+        let root_after = std::fs::read_to_string(repo.join("root.txt"))?;
+        assert_eq!(root_after, "root after\n");
+        let nested_after = std::fs::read_to_string(workspace.join("nested.txt"))?;
+        assert_eq!(nested_after, "nested modified\n");
+        assert!(!workspace.join("code-rs").exists());
+
+        Ok(())
+    }
+
+    #[test]
+    /// Restoring from a subdirectory preserves ignored files in parent folders.
+    fn restore_from_subdirectory_preserves_parent_vscode() -> Result<(), GitToolingError> {
+        let temp = tempfile::tempdir()?;
+        let repo = temp.path();
+        init_test_repo(repo);
+
+        let workspace = repo.join("code-rs");
+        std::fs::create_dir_all(&workspace)?;
+        std::fs::write(repo.join(".gitignore"), ".vscode/\n")?;
+        std::fs::write(workspace.join("tracked.txt"), "snapshot version\n")?;
+        run_git_in(repo, &["add", "."]);
+        run_git_in(
+            repo,
+            &[
+                "-c",
+                "user.name=Tester",
+                "-c",
+                "[email protected]",
+                "commit",
+                "-m",
+                "initial",
+            ],
+        );
+
+        std::fs::write(workspace.join("tracked.txt"), "snapshot delta\n")?;
+        let ghost = create_ghost_commit(&CreateGhostCommitOptions::new(&workspace))?;
+
+        std::fs::write(workspace.join("tracked.txt"), "post-snapshot\n")?;
+        let vscode = repo.join(".vscode");
+        std::fs::create_dir_all(&vscode)?;
+        std::fs::write(vscode.join("settings.json"), "{\n  \"after\": true\n}\n")?;
+
+        restore_ghost_commit(&workspace, &ghost)?;
+
+        let tracked_after = std::fs::read_to_string(workspace.join("tracked.txt"))?;
+        assert_eq!(tracked_after, "snapshot delta\n");
+        assert!(vscode.join("settings.json").exists());
+        let settings_after = std::fs::read_to_string(vscode.join("settings.json"))?;
+        assert_eq!(settings_after, "{\n  \"after\": true\n}\n");
+
+        Ok(())
+    }
+
+    #[test]
+    /// Restoring from the repository root keeps ignored files intact.
+    fn restore_preserves_ignored_files() -> Result<(), GitToolingError> {
+        let temp = tempfile::tempdir()?;
+        let repo = temp.path();
+        init_test_repo(repo);
+
+        std::fs::write(repo.join(".gitignore"), ".vscode/\n")?;
+        std::fs::write(repo.join("tracked.txt"), "snapshot version\n")?;
+        let vscode = repo.join(".vscode");
+        std::fs::create_dir_all(&vscode)?;
+        std::fs::write(vscode.join("settings.json"), "{\n  \"before\": true\n}\n")?;
+        run_git_in(repo, &["add", ".gitignore", "tracked.txt"]);
+        run_git_in(
+            repo,
+            &[
+                "-c",
+                "user.name=Tester",
+                "-c",
+                "[email protected]",
+                "commit",
+                "-m",
+                "initial",
+            ],
+        );
+
+        std::fs::write(repo.join("tracked.txt"), "snapshot delta\n")?;
+        let ghost = create_ghost_commit(&CreateGhostCommitOptions::new(repo))?;
+
+        std::fs::write(repo.join("tracked.txt"), "post-snapshot\n")?;
+        std::fs::write(vscode.join("settings.json"), "{\n  \"after\": true\n}\n")?;
+        std::fs::write(repo.join("temp.txt"), "new file\n")?;
+
+        restore_ghost_commit(repo, &ghost)?;
+
+        let tracked_after = std::fs::read_to_string(repo.join("tracked.txt"))?;
+        assert_eq!(tracked_after, "snapshot delta\n");
+        assert!(vscode.join("settings.json").exists());
+        let settings_after = std::fs::read_to_string(vscode.join("settings.json"))?;
+        assert_eq!(settings_after, "{\n  \"after\": true\n}\n");
+        assert!(repo.join("temp.txt").exists());
+
+        Ok(())
+    }
+}

codex-rs/git-tooling/src/lib.rs

@@ -0,0 +1,43 @@
+use std::fmt;
+
+mod errors;
+mod ghost_commits;
+mod operations;
+mod platform;
+
+pub use errors::GitToolingError;
+pub use ghost_commits::CreateGhostCommitOptions;
+pub use ghost_commits::create_ghost_commit;
+pub use ghost_commits::restore_ghost_commit;
+pub use ghost_commits::restore_to_commit;
+pub use platform::create_symlink;
+
+/// Details of a ghost commit created from a repository state.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct GhostCommit {
+    id: String,
+    parent: Option<String>,
+}
+
+impl GhostCommit {
+    /// Create a new ghost commit wrapper from a raw commit ID and optional parent.
+    pub fn new(id: String, parent: Option<String>) -> Self {
+        Self { id, parent }
+    }
+
+    /// Commit ID for the snapshot.
+    pub fn id(&self) -> &str {
+        &self.id
+    }
+
+    /// Parent commit ID, if the repository had a `HEAD` at creation time.
+    pub fn parent(&self) -> Option<&str> {
+        self.parent.as_deref()
+    }
+}
+
+impl fmt::Display for GhostCommit {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{}", self.id)
+    }
+}

codex-rs/git-tooling/src/operations.rs

@@ -0,0 +1,218 @@
+use std::ffi::OsStr;
+use std::ffi::OsString;
+use std::path::Component;
+use std::path::Path;
+use std::path::PathBuf;
+use std::process::Command;
+
+use crate::GitToolingError;
+
+pub(crate) fn ensure_git_repository(path: &Path) -> Result<(), GitToolingError> {
+    match run_git_for_stdout(
+        path,
+        vec![
+            OsString::from("rev-parse"),
+            OsString::from("--is-inside-work-tree"),
+        ],
+        None,
+    ) {
+        Ok(output) if output.trim() == "true" => Ok(()),
+        Ok(_) => Err(GitToolingError::NotAGitRepository {
+            path: path.to_path_buf(),
+        }),
+        Err(GitToolingError::GitCommand { status, .. }) if status.code() == Some(128) => {
+            Err(GitToolingError::NotAGitRepository {
+                path: path.to_path_buf(),
+            })
+        }
+        Err(err) => Err(err),
+    }
+}
+
+pub(crate) fn resolve_head(path: &Path) -> Result<Option<String>, GitToolingError> {
+    match run_git_for_stdout(
+        path,
+        vec![
+            OsString::from("rev-parse"),
+            OsString::from("--verify"),
+            OsString::from("HEAD"),
+        ],
+        None,
+    ) {
+        Ok(sha) => Ok(Some(sha)),
+        Err(GitToolingError::GitCommand { status, .. }) if status.code() == Some(128) => Ok(None),
+        Err(other) => Err(other),
+    }
+}
+
+pub(crate) fn normalize_relative_path(path: &Path) -> Result<PathBuf, GitToolingError> {
+    let mut result = PathBuf::new();
+    let mut saw_component = false;
+    for component in path.components() {
+        saw_component = true;
+        match component {
+            Component::Normal(part) => result.push(part),
+            Component::CurDir => {}
+            Component::ParentDir => {
+                if !result.pop() {
+                    return Err(GitToolingError::PathEscapesRepository {
+                        path: path.to_path_buf(),
+                    });
+                }
+            }
+            Component::RootDir | Component::Prefix(_) => {
+                return Err(GitToolingError::NonRelativePath {
+                    path: path.to_path_buf(),
+                });
+            }
+        }
+    }
+
+    if !saw_component {
+        return Err(GitToolingError::NonRelativePath {
+            path: path.to_path_buf(),
+        });
+    }
+
+    Ok(result)
+}
+
+pub(crate) fn resolve_repository_root(path: &Path) -> Result<PathBuf, GitToolingError> {
+    let root = run_git_for_stdout(
+        path,
+        vec![
+            OsString::from("rev-parse"),
+            OsString::from("--show-toplevel"),
+        ],
+        None,
+    )?;
+    Ok(PathBuf::from(root))
+}
+
+pub(crate) fn apply_repo_prefix_to_force_include(
+    prefix: Option<&Path>,
+    paths: &[PathBuf],
+) -> Vec<PathBuf> {
+    if paths.is_empty() {
+        return Vec::new();
+    }
+
+    match prefix {
+        Some(prefix) => paths.iter().map(|path| prefix.join(path)).collect(),
+        None => paths.to_vec(),
+    }
+}
+
+pub(crate) fn repo_subdir(repo_root: &Path, repo_path: &Path) -> Option<PathBuf> {
+    if repo_root == repo_path {
+        return None;
+    }
+
+    repo_path
+        .strip_prefix(repo_root)
+        .ok()
+        .and_then(non_empty_path)
+        .or_else(|| {
+            let repo_root_canon = repo_root.canonicalize().ok()?;
+            let repo_path_canon = repo_path.canonicalize().ok()?;
+            repo_path_canon
+                .strip_prefix(&repo_root_canon)
+                .ok()
+                .and_then(non_empty_path)
+        })
+}
+
+fn non_empty_path(path: &Path) -> Option<PathBuf> {
+    if path.as_os_str().is_empty() {
+        None
+    } else {
+        Some(path.to_path_buf())
+    }
+}
+
+pub(crate) fn run_git_for_status<I, S>(
+    dir: &Path,
+    args: I,
+    env: Option<&[(OsString, OsString)]>,
+) -> Result<(), GitToolingError>
+where
+    I: IntoIterator<Item = S>,
+    S: AsRef<OsStr>,
+{
+    run_git(dir, args, env)?;
+    Ok(())
+}
+
+pub(crate) fn run_git_for_stdout<I, S>(
+    dir: &Path,
+    args: I,
+    env: Option<&[(OsString, OsString)]>,
+) -> Result<String, GitToolingError>
+where
+    I: IntoIterator<Item = S>,
+    S: AsRef<OsStr>,
+{
+    let run = run_git(dir, args, env)?;
+    String::from_utf8(run.output.stdout)
+        .map(|value| value.trim().to_string())
+        .map_err(|source| GitToolingError::GitOutputUtf8 {
+            command: run.command,
+            source,
+        })
+}
+
+fn run_git<I, S>(
+    dir: &Path,
+    args: I,
+    env: Option<&[(OsString, OsString)]>,
+) -> Result<GitRun, GitToolingError>
+where
+    I: IntoIterator<Item = S>,
+    S: AsRef<OsStr>,
+{
+    let iterator = args.into_iter();
+    let (lower, upper) = iterator.size_hint();
+    let mut args_vec = Vec::with_capacity(upper.unwrap_or(lower));
+    for arg in iterator {
+        args_vec.push(OsString::from(arg.as_ref()));
+    }
+    let command_string = build_command_string(&args_vec);
+    let mut command = Command::new("git");
+    command.current_dir(dir);
+    if let Some(envs) = env {
+        for (key, value) in envs {
+            command.env(key, value);
+        }
+    }
+    command.args(&args_vec);
+    let output = command.output()?;
+    if !output.status.success() {
+        let stderr = String::from_utf8_lossy(&output.stderr).trim().to_string();
+        return Err(GitToolingError::GitCommand {
+            command: command_string,
+            status: output.status,
+            stderr,
+        });
+    }
+    Ok(GitRun {
+        command: command_string,
+        output,
+    })
+}
+
+fn build_command_string(args: &[OsString]) -> String {
+    if args.is_empty() {
+        return "git".to_string();
+    }
+    let joined = args
+        .iter()
+        .map(|arg| arg.to_string_lossy().into_owned())
+        .collect::<Vec<_>>()
+        .join(" ");
+    format!("git {joined}")
+}
+
+struct GitRun {
+    command: String,
+    output: std::process::Output,
+}

codex-rs/git-tooling/src/platform.rs

@@ -0,0 +1,37 @@
+use std::path::Path;
+
+use crate::GitToolingError;
+
+#[cfg(unix)]
+pub fn create_symlink(
+    _source: &Path,
+    link_target: &Path,
+    destination: &Path,
+) -> Result<(), GitToolingError> {
+    use std::os::unix::fs::symlink;
+
+    symlink(link_target, destination)?;
+    Ok(())
+}
+
+#[cfg(windows)]
+pub fn create_symlink(
+    source: &Path,
+    link_target: &Path,
+    destination: &Path,
+) -> Result<(), GitToolingError> {
+    use std::os::windows::fs::FileTypeExt;
+    use std::os::windows::fs::symlink_dir;
+    use std::os::windows::fs::symlink_file;
+
+    let metadata = std::fs::symlink_metadata(source)?;
+    if metadata.file_type().is_symlink_dir() {
+        symlink_dir(link_target, destination)?;
+    } else {
+        symlink_file(link_target, destination)?;
+    }
+    Ok(())
+}
+
+#[cfg(not(any(unix, windows)))]
+compile_error!("codex-git-tooling symlink support is only implemented for Unix and Windows");

codex-rs/tui/Cargo.toml

@@ -37,6 +37,7 @@ codex-common = { path = "../common", features = [
 ] }
 codex-core = { path = "../core" }
 codex-file-search = { path = "../file-search" }
+codex-git-tooling = { path = "../git-tooling" }
 codex-login = { path = "../login" }
 codex-ollama = { path = "../ollama" }
 codex-protocol = { path = "../protocol" }

codex-rs/tui/src/app.rs

@@ -1485,6 +1485,9 @@ impl App<'_> {
                     };
 
                     match command {
+                        SlashCommand::Undo => {
+                            // Undo snapshots are handled directly within the chat widget.
+                        }
                         SlashCommand::Review => {
                             if let AppState::Chat { widget } = &mut self.app_state {
                                 widget.handle_review_command(command_args);

codex-rs/tui/src/chatwidget.rs

@@ -94,6 +94,13 @@ use codex_core::protocol::ProEvent;
 use codex_core::protocol::ProPhase;
 use codex_core::protocol::ProStats;
 use codex_core::protocol::ProCategory;
+use codex_git_tooling::{
+    create_ghost_commit,
+    restore_ghost_commit,
+    CreateGhostCommitOptions,
+    GhostCommit,
+    GitToolingError,
+};
 use crossterm::event::KeyEvent;
 use crossterm::event::KeyEventKind;
 use image::imageops::FilterType;
@@ -148,6 +155,7 @@ use crate::history_cell::HistoryCell;
 use crate::history_cell::HistoryCellType;
 use crate::history_cell::PatchEventType;
 use crate::history_cell::PlainHistoryCell;
+use crate::slash_command::SlashCommand;
 use crate::live_wrap::RowBuilder;
 use crate::streaming::StreamKind;
 use crate::streaming::controller::AppEventHistorySink;
@@ -244,6 +252,7 @@ const RATE_LIMIT_WARNING_THRESHOLDS: [f64; 3] = [50.0, 75.0, 90.0];
 const RATE_LIMIT_REFRESH_INTERVAL: chrono::Duration = chrono::Duration::minutes(10);
 
 const RATE_LIMIT_RESET_FILE: &str = "state/rate_limit_resets.json";
+const MAX_TRACKED_GHOST_COMMITS: usize = 20;
 
 #[derive(Default)]
 struct RateLimitWarningState {
@@ -416,6 +425,8 @@ pub(crate) struct ChatWidget<'a> {
     // a new turn; used to anchor the next turn window so assistant output
     // appears after them.
     pending_user_prompts_for_next_turn: usize,
+    ghost_snapshots: Vec<GhostCommit>,
+    ghost_snapshots_disabled: bool,
 
     // Event sequencing to preserve original order across streaming/tool events
     // and stream-related flags moved into stream_state
@@ -2218,6 +2229,8 @@ impl ChatWidget<'_> {
             queued_user_messages: std::collections::VecDeque::new(),
             pending_dispatched_user_messages: std::collections::VecDeque::new(),
             pending_user_prompts_for_next_turn: 0,
+            ghost_snapshots: Vec::new(),
+            ghost_snapshots_disabled: false,
             browser_is_external: false,
             // Stable ordering & routing init
             cell_order_seq: vec![OrderKey {
@@ -2440,6 +2453,8 @@ impl ChatWidget<'_> {
             queued_user_messages: std::collections::VecDeque::new(),
             pending_dispatched_user_messages: std::collections::VecDeque::new(),
             pending_user_prompts_for_next_turn: 0,
+            ghost_snapshots: Vec::new(),
+            ghost_snapshots_disabled: false,
             browser_is_external: false,
             // Strict ordering init for forked widget
             cell_order_seq: vec![OrderKey {
@@ -3585,6 +3600,10 @@ impl ChatWidget<'_> {
                 }
             }
             crate::slash_command::ProcessedCommand::RegularCommand(cmd, command_text) => {
+                if cmd == SlashCommand::Undo {
+                    self.undo_last_snapshot();
+                    return;
+                }
                 // This is a regular slash command, dispatch it normally
                 self.app_event_tx
                     .send(AppEvent::DispatchCommand(cmd, command_text));
@@ -3750,6 +3769,8 @@ impl ChatWidget<'_> {
             return;
         }
 
+        self.capture_ghost_snapshot();
+
         let turn_active = self.is_task_running()
             || !self.active_task_ids.is_empty()
             || self.stream.is_write_cycle_active()
@@ -3792,6 +3813,60 @@ impl ChatWidget<'_> {
         // (debug watchdog removed)
     }
 
+    fn capture_ghost_snapshot(&mut self) {
+        if self.ghost_snapshots_disabled {
+            return;
+        }
+
+        let options = CreateGhostCommitOptions::new(&self.config.cwd);
+        match create_ghost_commit(&options) {
+            Ok(commit) => {
+                self.ghost_snapshots.push(commit);
+                if self.ghost_snapshots.len() > MAX_TRACKED_GHOST_COMMITS {
+                    self.ghost_snapshots.remove(0);
+                }
+            }
+            Err(err) => {
+                self.ghost_snapshots_disabled = true;
+                let (message, hint) = match &err {
+                    GitToolingError::NotAGitRepository { .. } => (
+                        "Snapshots disabled: this workspace is not inside a Git repository.".to_string(),
+                        None,
+                    ),
+                    _ => (
+                        format!("Snapshots disabled after Git error: {err}"),
+                        Some(
+                            "Restart Code after resolving the issue to re-enable snapshots.".to_string(),
+                        ),
+                    ),
+                };
+                self.push_background_tail(message);
+                if let Some(hint) = hint {
+                    self.push_background_tail(hint);
+                }
+                tracing::warn!("failed to create ghost snapshot: {err}");
+            }
+        }
+    }
+
+    fn undo_last_snapshot(&mut self) {
+        let Some(commit) = self.ghost_snapshots.pop() else {
+            self.push_background_tail("No snapshot is available to restore.".to_string());
+            return;
+        };
+
+        if let Err(err) = restore_ghost_commit(&self.config.cwd, &commit) {
+            self.history_push(history_cell::new_error_event(format!(
+                "Failed to restore snapshot: {err}",
+            )));
+            self.ghost_snapshots.push(commit);
+            return;
+        }
+
+        let short_id: String = commit.id().chars().take(8).collect();
+        self.push_background_tail(format!("Restored workspace to snapshot {short_id}"));
+    }
+
     fn flush_pending_agent_notes(&mut self) {
         for note in self.pending_agent_notes.drain(..) {
             if let Err(e) = self.codex_op_tx.send(Op::AddToHistory { text: note }) {

codex-rs/tui/src/chatwidget/tests.rs

@@ -207,6 +207,10 @@ fn make_chatwidget_manual() -> (
         rate_limit_fetch_inflight: false,
         rate_limit_fetch_placeholder: None,
         rate_limit_fetch_ack_pending: false,
+        #[cfg(not(feature = "legacy_tests"))]
+        ghost_snapshots: Vec::new(),
+        #[cfg(not(feature = "legacy_tests"))]
+        ghost_snapshots_disabled: false,
         stream: StreamController::new(cfg),
         last_stream_kind: None,
         running_commands: HashMap::new(),

codex-rs/tui/src/slash_command.rs

@@ -21,6 +21,7 @@ pub enum SlashCommand {
     New,
     Init,
     Compact,
+    Undo,
     Review,
     Diff,
     Mention,
@@ -69,6 +70,7 @@ impl SlashCommand {
             SlashCommand::New => "start a new chat during a conversation",
             SlashCommand::Init => "create an AGENTS.md file with instructions for Code",
             SlashCommand::Compact => "summarize conversation to prevent hitting the context limit",
+            SlashCommand::Undo => "restore the workspace to the last Code snapshot",
             SlashCommand::Review => "review your changes for potential issues",
             SlashCommand::Quit => "exit Code",
             SlashCommand::Diff => "show git diff (including untracked files)",

docs/slash-commands.md

@@ -25,6 +25,7 @@ Notes
 
 - `/init`: create an `AGENTS.md` file with instructions for Codex.
 - `/diff`: show `git diff` (including untracked files).
+- `/undo`: restore the workspace to the most recent Code snapshot.
 - `/branch [task]`: create a worktree branch and switch to it. If a
   task/description is provided, it is used when naming the branch. Must be run
   from the repository root (not inside another branch worktree).