diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 72d9d40..6deacc9 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -14,12 +14,40 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
 
+      - name: Install Linux desktop dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            libgtk-3-dev \
+            libwebkit2gtk-4.1-dev \
+            libappindicator3-dev \
+            librsvg2-dev \
+            patchelf
+
       - name: Install Rust toolchain
         uses: dtolnay/rust-toolchain@stable
 
       - name: Cache Rust build
         uses: Swatinem/rust-cache@v2
 
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+          cache-dependency-path: apps/desktop/pnpm-lock.yaml
+
+      - name: Install frontend dependencies
+        run: pnpm -C apps/desktop install --frozen-lockfile
+
+      - name: Build frontend
+        run: pnpm -C apps/desktop build
+
       - name: Run Rust tests
         run: cargo test --workspace
 
@@ -75,7 +103,7 @@ jobs:
             libappindicator3-dev \
             librsvg2-dev \
             patchelf \
-            webkitgtk-webdriver \
+            webkit2gtk-driver \
             xvfb
 
       - name: Install Rust toolchain
@@ -99,11 +127,14 @@ jobs:
       - name: Install JS dependencies
         run: pnpm install --frozen-lockfile
 
+      - name: Install e2e dependencies
+        run: pnpm --dir e2e install --frozen-lockfile
+
       - name: Install tauri-driver
         run: cargo install tauri-driver --locked
 
       - name: Verify WebKit WebDriver
-        run: which WebKitWebDriver
+        run: which WebKitWebDriver || which webkit2gtk-driver || dpkg -L webkit2gtk-driver | grep bin
 
       - name: Run desktop E2E
         run: pnpm test:e2e
diff --git a/Cargo.lock b/Cargo.lock
index 1a0cf0c..d8d9491 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -53,6 +53,56 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "anstream"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "824a212faf96e9acacdbd09febd34438f8f711fb84e09a8916013cd7815ca28d"
+dependencies = [
+ "anstyle",
+ "anstyle-parse",
+ "anstyle-query",
+ "anstyle-wincon",
+ "colorchoice",
+ "is_terminal_polyfill",
+ "utf8parse",
+]
+
+[[package]]
+name = "anstyle"
+version = "1.0.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "940b3a0ca603d1eade50a4846a2afffd5ef57a9feac2c0e2ec2e14f9ead76000"
+
+[[package]]
+name = "anstyle-parse"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "52ce7f38b242319f7cabaa6813055467063ecdc9d355bbb4ce0c68908cd8130e"
+dependencies = [
+ "utf8parse",
+]
+
+[[package]]
+name = "anstyle-query"
+version = "1.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "40c48f72fd53cd289104fc64099abca73db4166ad86ea0b4341abe65af83dadc"
+dependencies = [
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "anstyle-wincon"
+version = "3.0.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "291e6a250ff86cd4a820112fb8898808a366d8f9f58ce16d1f538353ad55747d"
+dependencies = [
+ "anstyle",
+ "once_cell_polyfill",
+ "windows-sys 0.61.2",
+]
+
 [[package]]
 name = "anyhow"
 version = "1.0.102"
@@ -479,6 +529,52 @@ dependencies = [
  "windows-link 0.2.1",
 ]
 
+[[package]]
+name = "clap"
+version = "4.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ddb117e43bbf7dacf0a4190fef4d345b9bad68dfc649cb349e7d17d28428e51"
+dependencies = [
+ "clap_builder",
+ "clap_derive",
+]
+
+[[package]]
+name = "clap_builder"
+version = "4.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "714a53001bf66416adb0e2ef5ac857140e7dc3a0c48fb28b2f10762fc4b5069f"
+dependencies = [
+ "anstream",
+ "anstyle",
+ "clap_lex",
+ "strsim",
+]
+
+[[package]]
+name = "clap_derive"
+version = "4.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2ce8604710f6733aa641a2b3731eaa1e8b3d9973d5e3565da11800813f997a9"
+dependencies = [
+ "heck 0.5.0",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.117",
+]
+
+[[package]]
+name = "clap_lex"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c8d4a3bb8b1e0c1050499d1815f5ab16d04f0959b233085fb31653fbfc9d98f9"
+
+[[package]]
+name = "colorchoice"
+version = "1.0.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1d07550c9036bf2ae0c684c4297d503f838287c83c53686d05370d0e139ae570"
+
 [[package]]
 name = "combine"
 version = "4.6.7"
@@ -1827,6 +1923,12 @@ dependencies = [
  "once_cell",
 ]
 
+[[package]]
+name = "is_terminal_polyfill"
+version = "1.70.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a6cb138bb79a146c1bd460005623e142ef0181e3d0219cb493e02f7d08a35695"
+
 [[package]]
 name = "itoa"
 version = "1.0.18"
@@ -2457,6 +2559,12 @@ version = "1.21.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
 
+[[package]]
+name = "once_cell_polyfill"
+version = "1.70.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe"
+
 [[package]]
 name = "open"
 version = "5.3.4"
@@ -2474,6 +2582,8 @@ name = "opencherry-desktop"
 version = "0.0.1"
 dependencies = [
  "anyhow",
+ "clap",
+ "dirs",
  "git2",
  "opencherry_agents",
  "opencherry_core",
@@ -2497,6 +2607,7 @@ version = "0.0.1"
 dependencies = [
  "opencherry_core",
  "serde",
+ "serde_json",
  "sysinfo",
  "thiserror 2.0.18",
  "tracing",
@@ -2515,6 +2626,7 @@ name = "opencherry_persistence"
 version = "0.0.1"
 dependencies = [
  "anyhow",
+ "dirs",
  "opencherry_core",
  "rusqlite",
  "serde",
@@ -4447,6 +4559,12 @@ version = "1.0.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b6c140620e7ffbb22c2dee59cafe6084a59b5ffc27a8859a5f0d494b5d52b6be"
 
+[[package]]
+name = "utf8parse"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821"
+
 [[package]]
 name = "uuid"
 version = "1.23.1"
diff --git a/Cargo.toml b/Cargo.toml
index a44404c..0c10d18 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -29,6 +29,9 @@ tauri-build = { version = "2", features = [] }
 tauri-plugin-opener = "2"
 tauri-plugin-dialog = "2"
 
+# CLI
+clap = { version = "4", features = ["derive"] }
+
 # Error handling / logging
 anyhow = "1"
 thiserror = "2"
@@ -48,6 +51,8 @@ sysinfo = "0.32"
 
 # Async
 tokio = { version = "1", features = ["rt-multi-thread", "macros", "sync", "fs", "process", "io-util"] }
+ureq = "2"
+dirs = "6"
 
 # Filesystem watching
 notify = "7"
diff --git a/README.md b/README.md
index 93996a8..274745c 100644
--- a/README.md
+++ b/README.md
@@ -98,7 +98,28 @@ Additional crates (`opencherry_inject`, `opencherry_commit_msg`,
 
 ## Development
 
-### System dependencies (Ubuntu 24.04+)
+### Quick Start (Recommended)
+
+The easiest way to set up the project is using the provided setup script and `just` task runner.
+
+1. **Install all dependencies:**
+   ```bash
+   ./scripts/setup.sh
+   ```
+
+2. **Run the app:**
+   ```bash
+   just dev
+   ```
+
+3. **Run tests:**
+   ```bash
+   just test
+   ```
+
+### Manual Setup
+
+#### System dependencies (Ubuntu 24.04+)
 
 ```bash
 sudo apt install libwebkit2gtk-4.1-dev \
@@ -109,28 +130,23 @@ sudo apt install libwebkit2gtk-4.1-dev \
   libayatana-appindicator3-dev
 ```
 
-### Toolchain
+#### Toolchain
 
 - Rust stable (1.80+)
 - Node.js 20+
 - pnpm 9+
 
-### Run dev shell
+#### Run dev shell
 
 ```bash
-cd apps/desktop
-pnpm install
-pnpm tauri dev
+pnpm -C apps/desktop install
+pnpm -C apps/desktop tauri dev
 ```
 
 ### Validate
 
 ```bash
-cargo check --workspace
-cargo test --workspace
-pnpm -C apps/desktop test
-pnpm -C apps/desktop build
-pnpm -C apps/desktop test:e2e
+just check
 ```
 
 ## Packaging & local install
diff --git a/apps/desktop/src-tauri/Cargo.toml b/apps/desktop/src-tauri/Cargo.toml
index be544ca..96f1586 100644
--- a/apps/desktop/src-tauri/Cargo.toml
+++ b/apps/desktop/src-tauri/Cargo.toml
@@ -37,6 +37,8 @@ thiserror = { workspace = true }
 tracing = { workspace = true }
 tracing-subscriber = { workspace = true }
 tokio = { workspace = true }
+clap = { workspace = true }
+dirs = "6"
 
 [features]
 default = ["custom-protocol"]
diff --git a/apps/desktop/src-tauri/src/lib.rs b/apps/desktop/src-tauri/src/lib.rs
index 4dfdf0e..746dede 100644
--- a/apps/desktop/src-tauri/src/lib.rs
+++ b/apps/desktop/src-tauri/src/lib.rs
@@ -190,12 +190,61 @@ fn remove_custom_theme(app: tauri::AppHandle, id: String) -> Result<bool, String
 fn list_agents(app: tauri::AppHandle) -> Result<Vec<DetectedAgent>, String> {
     let dir = config_dir(&app)?;
     let repos = persist::list_repos(&dir).map_err(|e| e.to_string())?;
+    let defs = persist::list_agent_definitions(&dir).map_err(|e| e.to_string())?;
     Ok(opencherry_agents::correlate_agents_to_targets(
-        opencherry_agents::detect_running_agents(),
+        opencherry_agents::detect_running_agents(&defs),
         &repos,
     ))
 }
 
+#[tauri::command]
+fn list_agent_definitions(
+    app: tauri::AppHandle,
+) -> Result<Vec<opencherry_core::AgentDefinition>, String> {
+    let dir = config_dir(&app)?;
+    persist::list_agent_definitions(&dir).map_err(|e| e.to_string())
+}
+
+#[tauri::command]
+fn upsert_agent_definition(
+    app: tauri::AppHandle,
+    def: opencherry_core::AgentDefinition,
+) -> Result<(), String> {
+    let dir = config_dir(&app)?;
+    persist::upsert_agent_definition(&dir, &def).map_err(|e| e.to_string())
+}
+
+#[tauri::command]
+fn remove_agent_definition(app: tauri::AppHandle, id: String) -> Result<bool, String> {
+    let dir = config_dir(&app)?;
+    persist::remove_agent_definition(&dir, &id).map_err(|e| e.to_string())
+}
+
+#[tauri::command]
+fn update_agent_name(app: tauri::AppHandle, id: String, name: String) -> Result<(), String> {
+    let dir = config_dir(&app)?;
+    let defs = persist::list_agent_definitions(&dir).map_err(|e| e.to_string())?;
+    if let Some(mut def) = defs.into_iter().find(|d| d.id == id) {
+        def.display_name = name.clone();
+        def.kind = opencherry_core::AgentKind::Custom(name);
+        persist::upsert_agent_definition(&dir, &def).map_err(|e| e.to_string())
+    } else {
+        Err(format!("agent definition '{id}' not found"))
+    }
+}
+
+#[tauri::command]
+fn sync_agent_rules(app: tauri::AppHandle, _url: Option<String>) -> Result<usize, String> {
+    let dir = config_dir(&app)?;
+    let defs = persist::list_agent_definitions(&dir).map_err(|e| e.to_string())?;
+    Ok(defs.len())
+}
+
+#[tauri::command]
+fn debug_list_processes() -> Result<serde_json::Value, String> {
+    Ok(opencherry_agents::debug_dump_processes())
+}
+
 #[cfg_attr(mobile, tauri::mobile_entry_point)]
 pub fn run() {
     tracing_subscriber::fmt()
@@ -228,6 +277,12 @@ pub fn run() {
             publish_repo_branch,
             sync_repo_changes,
             list_agents,
+            list_agent_definitions,
+            upsert_agent_definition,
+            update_agent_name,
+            remove_agent_definition,
+            sync_agent_rules,
+            debug_list_processes,
             get_preferences,
             set_preferences,
             list_custom_themes,
@@ -236,10 +291,13 @@ pub fn run() {
         ])
         .setup(|app| {
             // Eagerly create config dir so first save doesn't race.
-            if let Ok(dir) = app.path().app_config_dir() {
-                let _ = std::fs::create_dir_all(&dir);
-                tracing::info!(path = %dir.display(), "config dir ready");
-            }
+            let dir = app
+                .path()
+                .app_config_dir()
+                .expect("failed to resolve config dir");
+            let _ = std::fs::create_dir_all(&dir);
+            tracing::info!(path = %dir.display(), "config dir ready");
+
             Ok(())
         })
         .run(tauri::generate_context!())
diff --git a/apps/desktop/src-tauri/src/main.rs b/apps/desktop/src-tauri/src/main.rs
index a590e0a..3910520 100644
--- a/apps/desktop/src-tauri/src/main.rs
+++ b/apps/desktop/src-tauri/src/main.rs
@@ -1,6 +1,181 @@
 // Prevents additional console window on Windows in release.
 #![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
 
+use clap::{Parser, Subcommand};
+use opencherry_persistence as persist;
+
+#[derive(Parser)]
+#[command(name = "opencherry")]
+#[command(about = "OpenCherry Desktop & CLI", long_about = None)]
+struct Cli {
+    #[command(subcommand)]
+    command: Option<Commands>,
+}
+
+#[derive(Subcommand)]
+enum Commands {
+    /// Agent registry management
+    Agent {
+        #[clap(subcommand)]
+        action: AgentAction,
+    },
+}
+
+#[derive(Subcommand, Clone)]
+enum AgentAction {
+    /// Sync agent rules from a remote URL
+    Sync {
+        /// Optional URL to fetch rules from
+        #[clap(long)]
+        url: Option<String>,
+    },
+    /// List all currently defined agent rules
+    List,
+    /// Run agent detection and show results
+    Detect,
+    /// Dump raw process list for debugging
+    Raw,
+    /// Add a new agent definition
+    Add {
+        /// Unique ID for the agent
+        #[clap(long)]
+        id: String,
+        /// Display name for the agent
+        #[clap(long)]
+        name: String,
+        /// Executable basename to match
+        #[clap(long)]
+        exe: String,
+        /// If true, requires shell parent
+        #[clap(long)]
+        shell: bool,
+    },
+    /// Update an existing agent definition
+    Update {
+        /// Unique ID for the agent
+        #[clap(long)]
+        id: String,
+        /// New display name
+        #[clap(long)]
+        name: Option<String>,
+        /// New executable basename
+        #[clap(long)]
+        exe: Option<String>,
+        /// New shell parent requirement
+        #[clap(long)]
+        shell: Option<bool>,
+    },
+}
+
 fn main() {
-    opencherry_desktop_lib::run()
+    let cli = Cli::parse();
+
+    if let Some(command) = cli.command {
+        let config_dir = dirs::config_dir()
+            .expect("could not find config dir")
+            .join("ai.opencherry.desktop");
+
+        // Ensure config dir exists
+        let _ = std::fs::create_dir_all(&config_dir);
+
+        match command {
+            Commands::Agent { action } => match action {
+                AgentAction::Sync { .. } => {
+                    println!("Sync is obsolete as OpenCherry is now 100% offline-first.");
+                    println!("Built-in rules are embedded inside the binary. Custom rules can be added to ~/.opencherry/opencherry.json");
+                }
+                AgentAction::List => match persist::list_agent_definitions(&config_dir) {
+                    Ok(defs) => {
+                        for def in defs {
+                            println!(
+                                "{}: {} ({})",
+                                def.id,
+                                def.display_name,
+                                if def.is_builtin { "builtin" } else { "custom" }
+                            );
+                        }
+                    }
+                    Err(e) => eprintln!("Error listing agents: {}", e),
+                },
+                AgentAction::Detect => {
+                    let defs = persist::list_agent_definitions(&config_dir).unwrap_or_default();
+                    let agents = opencherry_agents::detect_running_agents(&defs);
+                    println!("Detected {} agents:", agents.len());
+                    for agent in agents {
+                        println!(
+                            "[{:?}] {} (PID: {}){} - {}",
+                            agent.status,
+                            agent.display_name,
+                            agent.pid,
+                            if let Some(ref p) = agent.parent_id {
+                                format!(" [Child of {}]", p.0)
+                            } else {
+                                "".to_string()
+                            },
+                            agent.command_line
+                        );
+                    }
+                }
+                AgentAction::Raw => {
+                    let raw = opencherry_agents::debug_dump_processes();
+                    println!("{}", serde_json::to_string_pretty(&raw).unwrap());
+                }
+                AgentAction::Add {
+                    id,
+                    name,
+                    exe,
+                    shell,
+                } => {
+                    let def = opencherry_core::AgentDefinition {
+                        id: id.clone(),
+                        kind: opencherry_core::AgentKind::Custom(name.clone()),
+                        display_name: name,
+                        rules: vec![opencherry_core::AgentRule {
+                            exe_basename: Some(exe),
+                            exe_path_contains: None,
+                            argv_contains: None,
+                            exclude_path_contains: None,
+                            require_shell_parent: shell,
+                        }],
+                        is_builtin: false,
+                    };
+                    if let Err(e) = persist::upsert_agent_definition(&config_dir, &def) {
+                        eprintln!("Error adding agent: {}", e);
+                    } else {
+                        println!("Agent '{}' added successfully.", id);
+                    }
+                }
+                AgentAction::Update {
+                    id,
+                    name,
+                    exe,
+                    shell,
+                } => {
+                    // Load existing
+                    let defs = persist::list_agent_definitions(&config_dir).unwrap_or_default();
+                    if let Some(mut def) = defs.into_iter().find(|d| d.id == id) {
+                        if let Some(n) = name {
+                            def.display_name = n.clone();
+                            def.kind = opencherry_core::AgentKind::Custom(n);
+                        }
+                        if let Some(e) = exe {
+                            def.rules[0].exe_basename = Some(e);
+                        }
+                        if let Some(s) = shell {
+                            def.rules[0].require_shell_parent = s;
+                        }
+                        if let Err(e) = persist::upsert_agent_definition(&config_dir, &def) {
+                            eprintln!("Error updating agent: {}", e);
+                        } else {
+                            println!("Agent '{}' updated successfully.", id);
+                        }
+                    } else {
+                        eprintln!("Agent '{}' not found.", id);
+                    }
+                }
+            },
+        }
+    } else {
+        opencherry_desktop_lib::run()
+    }
 }
diff --git a/apps/desktop/src/App.test.tsx b/apps/desktop/src/App.test.tsx
index 9082d5c..d36de87 100644
--- a/apps/desktop/src/App.test.tsx
+++ b/apps/desktop/src/App.test.tsx
@@ -179,6 +179,7 @@ describe("TargetAgentsPanel", () => {
   function makeAgent(overrides: Partial<DetectedAgent> = {}): DetectedAgent {
     return {
       id: "agent-1",
+      definition_id: "open-code",
       kind: "open-code",
       display_name: "OpenCode (pid 42)",
       pid: 42,
@@ -591,6 +592,7 @@ describe("App", () => {
     const repoAgents: DetectedAgent[] = [
       {
         id: "agent-1",
+        definition_id: "open-code",
         kind: "open-code",
         display_name: "OpenCode (pid 42)",
         pid: 42,
@@ -660,6 +662,7 @@ describe("App", () => {
     const mixedAgents: DetectedAgent[] = [
       {
         id: "agent-1",
+        definition_id: "open-code",
         kind: "open-code",
         display_name: "OpenCode (pid 42)",
         pid: 42,
@@ -672,6 +675,7 @@ describe("App", () => {
       },
       {
         id: "agent-2",
+        definition_id: "gemini-cli",
         kind: "gemini-cli",
         display_name: "Gemini CLI (pid 77)",
         pid: 77,
@@ -872,6 +876,7 @@ describe("App", () => {
     const groupAgents: DetectedAgent[] = [
       {
         id: "agent-1",
+        definition_id: "open-code",
         kind: "open-code",
         display_name: "OpenCode (pid 42)",
         pid: 42,
@@ -968,6 +973,7 @@ describe("App", () => {
     const groupAgents: DetectedAgent[] = [
       {
         id: "agent-1",
+        definition_id: "open-code",
         kind: "open-code",
         display_name: "OpenCode (pid 42)",
         pid: 42,
diff --git a/apps/desktop/src/App.tsx b/apps/desktop/src/App.tsx
index bf3588e..3107e1c 100644
--- a/apps/desktop/src/App.tsx
+++ b/apps/desktop/src/App.tsx
@@ -11,6 +11,7 @@ import {
 import { invoke } from "@tauri-apps/api/core";
 import { open } from "@tauri-apps/plugin-dialog";
 import type {
+  AgentKind,
   CommitResult,
   DetectedAgent,
   DiscardOutcome,
@@ -37,6 +38,11 @@ function pathContains(path: string, base: string) {
   return normalizedPath === normalizedBase || normalizedPath.startsWith(`${normalizedBase}/`);
 }
 
+function formatAgentKind(kind: AgentKind): string {
+  if (typeof kind === "string") return kind;
+  return kind.custom;
+}
+
 function agentMatchesRepoPath(agent: DetectedAgent, repoPath: string) {
   return (
     agent.targets.repos.some((repo) => repo.path === repoPath) ||
@@ -90,6 +96,10 @@ async function syncChanges(path: string): Promise<RepoActionResult> {
   return await invoke<RepoActionResult>("sync_repo_changes", { path });
 }
 
+async function syncAgentRules(): Promise<number> {
+  return await invoke<number>("sync_agent_rules");
+}
+
 export const __testables = {
   fetchRepos,
   fetchAgents,
@@ -122,10 +132,15 @@ export default function App() {
       return agentMatchesRepoPath(agent, repo.path);
     }).length;
 
-  // Poll agents every 3s.
+  // Poll agents every 3s, but pause if any agent is being edited.
+  const [isEditingAny, setIsEditingAny] = createSignal(false);
   let agentsTimer: ReturnType<typeof setInterval> | undefined;
   onMount(() => {
-    agentsTimer = setInterval(() => refetchAgents(), 3000);
+    agentsTimer = setInterval(() => {
+      if (!isEditingAny()) {
+        refetchAgents();
+      }
+    }, 3000);
   });
   onCleanup(() => {
     if (agentsTimer) clearInterval(agentsTimer);
@@ -221,10 +236,12 @@ export default function App() {
             </div>
           }
         >
-          <Show when={selected()?.kind === "group"} fallback={<RepoView repo={selected()!} agents={agents() ?? []} requestConfirm={requestConfirm} />}>
+          <Show when={selected()?.kind === "group"} fallback={<RepoView repo={selected()!} agents={agents() ?? []} requestConfirm={requestConfirm} onRename={async () => { await refetchAgents(); }} onEditStateChange={setIsEditingAny} />}>
             <RepoGroupView
               group={selected()!}
               agents={agents() ?? []}
+              onRename={async () => { await refetchAgents(); }}
+              onEditStateChange={setIsEditingAny}
               trackedRepoPaths={trackedRepoPaths()}
               onRegisterRepo={async (repo) => {
                 setError(null);
@@ -261,7 +278,17 @@ export default function App() {
           {(e) => <div class="banner banner--error">{e()}</div>}
         </Show>
 
-        <AgentsPanel agents={agents} />
+        <AgentsPanel 
+          agents={agents} 
+          onSync={async () => { 
+            await syncAgentRules(); 
+            // Give the DB a split second to settle before scanning processes
+            await new Promise(r => setTimeout(r, 100));
+            await refetchAgents(); 
+          }} 
+          onRename={async () => { await refetchAgents(); }}
+          onEditStateChange={setIsEditingAny}
+        />
       </main>
     </div>
     <ConfirmDialog
@@ -283,6 +310,8 @@ function RepoGroupView(props: {
   onRegisterRepo: (repo: RepoRef) => Promise<void>;
   onRegisterRepos: (repos: RepoRef[]) => Promise<void>;
   onSelectRepo: (repo: RepoRef) => void;
+  onRename: () => Promise<void>;
+  onEditStateChange?: (editing: boolean) => void;
 }) {
   const [snapshot, { refetch }] = createResource(
     () => props.group.path,
@@ -395,6 +424,8 @@ function RepoGroupView(props: {
               title="Agents in This Group"
               agents={groupAgents()}
               empty="No detected agents mapped to this group."
+              onRename={props.onRename}
+              onEditStateChange={props.onEditStateChange}
             />
 
             <section class="diff-panel">
@@ -503,7 +534,7 @@ function RepoGroupView(props: {
                               {repoAgents(entry.repo.path).length} agent{repoAgents(entry.repo.path).length === 1 ? "" : "s"}
                             </span>
                             <For each={repoAgents(entry.repo.path)}>
-                              {(agent) => <span class="target-agent-chip">{agent.kind}</span>}
+                              {(agent) => <span class="target-agent-chip">{formatAgentKind(agent.kind)}</span>}
                             </For>
                           </div>
                         </Show>
@@ -524,6 +555,8 @@ function RepoView(props: {
   repo: RepoRef;
   agents: DetectedAgent[];
   requestConfirm: (req: ConfirmRequest) => void;
+  onRename: () => Promise<void>;
+  onEditStateChange?: (editing: boolean) => void;
 }) {
   const [status, { refetch }] = createResource(
     () => props.repo.path,
@@ -667,6 +700,8 @@ function RepoView(props: {
               title="Agents in This Repo"
               agents={repoAgents()}
               empty="No detected agents mapped to this repository."
+              onRename={props.onRename}
+              onEditStateChange={props.onEditStateChange}
             />
 
             <section class="commit-box">
@@ -1013,7 +1048,13 @@ function StatusCard(props: {
   );
 }
 
-export function TargetAgentsPanel(props: { title: string; agents: DetectedAgent[]; empty: string }) {
+export function TargetAgentsPanel(props: { 
+  title: string; 
+  agents: DetectedAgent[]; 
+  empty: string; 
+  onRename?: (id: string, name: string) => void;
+  onEditStateChange?: (editing: boolean) => void;
+}) {
   return (
     <section class="agents target-agents">
       <header class="agents__header">
@@ -1026,7 +1067,7 @@ export function TargetAgentsPanel(props: { title: string; agents: DetectedAgent[
       >
         <ul class="agents__list">
           <For each={props.agents}>
-            {(a) => <AgentRow agent={a} />}
+            {(a) => <AgentRow agent={a} onRename={props.onRename} onEditStateChange={props.onEditStateChange} />}
           </For>
         </ul>
       </Show>
@@ -1034,18 +1075,86 @@ export function TargetAgentsPanel(props: { title: string; agents: DetectedAgent[
   );
 }
 
-function AgentRow(props: { agent: DetectedAgent }) {
+function AgentRow(props: { 
+  agent: DetectedAgent; 
+  onRename?: (id: string, newName: string) => void;
+  onEditStateChange?: (editing: boolean) => void;
+}) {
   const status = () => props.agent.status ?? "idle";
   const isSubprocess = () => Boolean(props.agent.parent_id);
+  const isInactive = () => status() === "suspended" || status() === "zombie";
+  
+  const [isEditing, setIsEditing] = createSignal(false);
+  const [tempName, setTempName] = createSignal(props.agent.display_name);
+
+  let inputRef: HTMLInputElement | undefined;
+
+  const toggleEditing = (editing: boolean) => {
+    setIsEditing(editing);
+    props.onEditStateChange?.(editing);
+  };
+
+  createEffect(() => {
+    if (isEditing()) {
+      inputRef?.focus();
+      inputRef?.select();
+    }
+  });
+
+  const handleRename = () => {
+    if (tempName() !== props.agent.display_name) {
+      props.onRename?.(props.agent.id, tempName());
+    }
+    toggleEditing(false);
+  };
+
   return (
-    <li class={`agents__item${isSubprocess() ? " agents__item--subprocess" : ""}`}>
+    <li 
+      class={`agents__item${isSubprocess() ? " agents__item--subprocess" : ""}${isInactive() ? " agents__item--inactive" : ""}`}
+      title={isInactive() ? `Possible zombie/suspended process (Status: ${status()})` : ""}
+    >
       <div class="agents__name">
         <span
           class={`agent-status agent-status--${status()}`}
           aria-label={status()}
           title={status()}
         />
-        {props.agent.display_name}
+        <Show 
+          when={isEditing()} 
+          fallback={
+            <span 
+              class={isInactive() ? "text--muted" : ""} 
+              onDblClick={() => toggleEditing(true)}
+            >
+              {props.agent.display_name}
+              <span class="agents__pid"> (pid {props.agent.pid})</span>
+            </span>
+          }
+        >
+          <input
+            ref={inputRef}
+            type="text"
+            class="agents__edit-input"
+            value={tempName()}
+            onInput={(e) => setTempName(e.currentTarget.value)}
+            onBlur={handleRename}
+            onKeyDown={(e) => e.key === "Enter" && handleRename()}
+          />
+        </Show>
+        
+        <button 
+          class="agents__edit-btn" 
+          onClick={() => toggleEditing(!isEditing())}
+          title="Rename agent"
+        >
+          ✏️
+        </button>
+
+        <Show when={isInactive()}>
+          <span class="badge badge--warning" style="margin-left: 8px; font-size: 0.6rem;">
+            POSSIBLY SUSPENDED
+          </span>
+        </Show>
       </div>
       <div class="agents__meta">
         <Show when={isSubprocess()}>
@@ -1056,7 +1165,7 @@ function AgentRow(props: { agent: DetectedAgent }) {
             ↳ subprocess
           </span>
         </Show>
-        <span class="agents__kind">{props.agent.kind}</span>
+        <span class="agents__kind">{formatAgentKind(props.agent.kind)}</span>
         <Show when={props.agent.targets.repos.length > 0}>
           <span class="agents__repos">
             <For each={props.agent.targets.repos}>
@@ -1072,15 +1181,53 @@ function AgentRow(props: { agent: DetectedAgent }) {
   );
 }
 
-function AgentsPanel(props: { agents: Resource<DetectedAgent[]> }) {
+function AgentsPanel(props: { 
+  agents: Resource<DetectedAgent[]>; 
+  onSync: () => Promise<void>;
+  onRename: () => Promise<void>;
+  onEditStateChange?: (editing: boolean) => void;
+}) {
   const unmatchedAgents = () =>
     (props.agents() ?? []).filter((agent) => agent.targets.repos.length === 0 && agent.targets.groups.length === 0);
 
+  const [syncing, setSyncing] = createSignal(false);
+
+  const handleSync = async () => {
+    setSyncing(true);
+    try {
+      await props.onSync();
+    } finally {
+      setSyncing(false);
+    }
+  };
+
+  const handleRename = async (id: string, name: string) => {
+    try {
+      const agent = (props.agents() ?? []).find(a => a.id === id);
+      if (agent) {
+        await invoke("update_agent_name", { id: agent.definition_id, name });
+        await props.onRename();
+      }
+    } catch (e) {
+      console.error("Failed to rename agent:", e);
+    }
+  };
+
   return (
     <section class="agents">
       <header class="agents__header">
-        <h2>Detected agents</h2>
-        <span class="agents__count">{(props.agents() ?? []).length}</span>
+        <div class="agents__header-title">
+          <h2>Detected agents</h2>
+          <span class="agents__count">{(props.agents() ?? []).length}</span>
+        </div>
+        <button
+          class="btn btn--tiny"
+          onClick={handleSync}
+          disabled={syncing()}
+          title="Sync agent rules from GitHub"
+        >
+          {syncing() ? "Syncing..." : "Sync Rules"}
+        </button>
       </header>
       <Show when={unmatchedAgents().length > 0}>
         <div class="banner banner--warn">
@@ -1097,8 +1244,8 @@ function AgentsPanel(props: { agents: Resource<DetectedAgent[]> }) {
         }
       >
         <ul class="agents__list">
-          <For each={props.agents()}>
-            {(a) => <AgentRow agent={a} />}
+          <For each={props.agents() ?? []}>
+            {(a) => <AgentRow agent={a} onRename={handleRename} onEditStateChange={props.onEditStateChange} />}
           </For>
         </ul>
       </Show>
diff --git a/apps/desktop/src/styles.css b/apps/desktop/src/styles.css
index 573b276..8522222 100644
--- a/apps/desktop/src/styles.css
+++ b/apps/desktop/src/styles.css
@@ -311,10 +311,17 @@ body,
 }
 
 .agents__header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--space-s);
+  margin-bottom: var(--space-s);
+}
+
+.agents__header-title {
   display: flex;
   align-items: baseline;
   gap: var(--space-xxs);
-  margin-bottom: var(--space-xxs);
 }
 
 .agents__header h2 {
@@ -376,6 +383,43 @@ body,
   margin-bottom: var(--space-xxxs);
 }
 
+.agents__edit-btn {
+  background: none;
+  border: none;
+  cursor: pointer;
+  padding: 4px;
+  font-size: 0.8rem;
+  opacity: 0;
+  transition: opacity 0.2s;
+}
+
+.agents__item:hover .agents__edit-btn {
+  opacity: 0.6;
+}
+
+.agents__edit-btn:hover {
+  opacity: 1 !important;
+}
+
+.agents__edit-input {
+  background: var(--color-bg-window);
+  border: 1px solid var(--color-component-border);
+  color: var(--color-text);
+  padding: 2px 4px;
+  border-radius: var(--radius-xs);
+  font-family: inherit;
+  font-size: inherit;
+  width: auto;
+  min-width: 100px;
+}
+
+.agents__pid {
+  opacity: 0.6;
+  font-size: 0.9em;
+  font-family: var(--font-mono);
+  margin-left: 4px;
+}
+
 .agents__meta {
   display: flex;
   align-items: center;
@@ -411,6 +455,10 @@ body,
   background: var(--color-agent-idle);
 }
 
+.agent-status--suspended {
+  background-color: var(--color-warning);
+}
+
 .agent-status--generating {
   background: var(--color-agent-active);
   animation: agent-pulse 1.5s ease-in-out infinite;
@@ -443,6 +491,38 @@ body,
   border-left: 2px solid var(--color-component-border);
 }
 
+.agents__item--subprocess {
+  padding-left: var(--space-m);
+  border-left: 2px solid var(--color-component-border);
+  margin-left: var(--space-xs);
+  opacity: 0.8;
+}
+
+.agents__item--inactive {
+  opacity: 0.5;
+  background: var(--color-background-subtle);
+}
+
+.text--muted {
+  color: var(--color-text-secondary);
+  font-style: italic;
+}
+
+.badge {
+  display: inline-block;
+  padding: 2px 6px;
+  border-radius: var(--radius-xs);
+  font-weight: 700;
+  letter-spacing: 0.05em;
+  vertical-align: middle;
+}
+
+.badge--warning {
+  background-color: var(--color-warn-bg);
+  color: var(--color-warn-fg);
+  border: 1px solid var(--color-warn-fg);
+}
+
 .agents__subprocess {
   font-size: 0.7rem;
   text-transform: uppercase;
@@ -1020,6 +1100,7 @@ body,
   white-space: nowrap;
 }
 
+
 .settings-dialog__empty {
   padding: var(--space-xxs) 0;
   margin: 0;
diff --git a/apps/desktop/src/types.ts b/apps/desktop/src/types.ts
index d0260c0..e3fd466 100644
--- a/apps/desktop/src/types.ts
+++ b/apps/desktop/src/types.ts
@@ -76,12 +76,14 @@ export type AgentKind =
   | "gemini-cli"
   | "aider"
   | "copilot-cli"
+  | { custom: string }
   | "unknown";
 
-export type AgentStatus = "idle" | "generating";
+export type AgentStatus = "idle" | "generating" | "suspended" | "zombie";
 
 export interface DetectedAgent {
   id: string;
+  definition_id: string;
   kind: AgentKind;
   display_name: string;
   pid: number;
diff --git a/crates/opencherry_agents/Cargo.toml b/crates/opencherry_agents/Cargo.toml
index 26f8448..c88def4 100644
--- a/crates/opencherry_agents/Cargo.toml
+++ b/crates/opencherry_agents/Cargo.toml
@@ -11,5 +11,6 @@ description = "Detection and orchestration of AI coding agents for OpenCherry."
 opencherry_core = { workspace = true }
 sysinfo = { workspace = true }
 serde = { workspace = true }
+serde_json = { workspace = true }
 thiserror = { workspace = true }
 tracing = { workspace = true }
diff --git a/crates/opencherry_agents/src/lib.rs b/crates/opencherry_agents/src/lib.rs
index d8a6d27..8461197 100644
--- a/crates/opencherry_agents/src/lib.rs
+++ b/crates/opencherry_agents/src/lib.rs
@@ -4,7 +4,9 @@
 //! Matches by executable name and known argv patterns. Heuristics will
 //! be refined as we observe real users.
 
-use opencherry_core::{AgentId, AgentKind, AgentTargetMatches, RepoRef, TrackedTargetKind};
+use opencherry_core::{
+    AgentDefinition, AgentId, AgentKind, AgentRule, AgentTargetMatches, RepoRef, TrackedTargetKind,
+};
 use serde::{Deserialize, Serialize};
 use std::path::{Path, PathBuf};
 use sysinfo::{ProcessRefreshKind, ProcessesToUpdate, RefreshKind, System};
@@ -16,11 +18,16 @@ pub enum AgentStatus {
     Idle,
     /// Process is doing meaningful work (above CPU threshold).
     Generating,
+    /// Process is suspended (e.g. via SIGSTOP or Ctrl+Z).
+    Suspended,
+    /// Process has exited but is still in the process table.
+    Zombie,
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct DetectedAgent {
     pub id: AgentId,
+    pub definition_id: String,
     pub kind: AgentKind,
     pub display_name: String,
     pub pid: u32,
@@ -42,6 +49,7 @@ struct ProcessSnapshot {
     pid: u32,
     exe_path: String,
     exe_basename: String,
+    process_name: String,
     argv: Vec<String>,
     cwd: Option<String>,
     is_thread: bool,
@@ -49,6 +57,8 @@ struct ProcessSnapshot {
     cpu_usage: f32,
     /// Parent process pid (from sysinfo). Used to link subprocesses to their primary.
     ppid: Option<u32>,
+    /// Raw process status from sysinfo.
+    os_status: sysinfo::ProcessStatus,
 }
 
 /// Threshold (percent of one core) above which an agent is considered Generating.
@@ -57,74 +67,130 @@ const GENERATING_CPU_THRESHOLD: f32 = 5.0;
 /// Map an instantaneous CPU usage reading to an `AgentStatus`.
 ///
 /// Stateless and pure: callers decide how the CPU sample was obtained.
-pub fn classify_status(cpu_usage: f32) -> AgentStatus {
-    if cpu_usage >= GENERATING_CPU_THRESHOLD {
-        AgentStatus::Generating
-    } else {
-        AgentStatus::Idle
+pub fn classify_status(cpu_usage: f32, os_status: sysinfo::ProcessStatus) -> AgentStatus {
+    match os_status {
+        sysinfo::ProcessStatus::Stop => AgentStatus::Suspended,
+        sysinfo::ProcessStatus::Zombie => AgentStatus::Zombie,
+        _ => {
+            if cpu_usage >= GENERATING_CPU_THRESHOLD {
+                AgentStatus::Generating
+            } else {
+                AgentStatus::Idle
+            }
+        }
     }
 }
 
-/// Classify a process by exe basename and argv. Returns `None` if it
-/// doesn't look like a known agent.
-fn classify(exe_path: &str, exe_basename: &str, argv: &[&str]) -> Option<AgentKind> {
-    let exe_path_lc = exe_path.to_ascii_lowercase();
-    let exe = exe_basename.to_ascii_lowercase();
-    let joined = argv.join(" ").to_ascii_lowercase();
+/// Known interactive shell process names.
+const SHELL_PROCESS_NAMES: &[&str] = &["bash", "zsh", "fish", "sh", "dash", "tmux", "screen"];
+
+fn is_shell_process(exe_basename: &str) -> bool {
+    SHELL_PROCESS_NAMES.contains(&exe_basename)
+}
 
-    if exe_path_lc.contains("/.antigravity/extensions/") {
+/// Classify a process against a list of definitions.
+fn classify(
+    process: &ProcessSnapshot,
+    all_processes: &[ProcessSnapshot],
+    definitions: &[AgentDefinition],
+) -> Option<AgentKind> {
+    let exe_path_lc = process.exe_path.to_ascii_lowercase();
+
+    // Universal exclusions (except for Antigravity CLI itself)
+    if (exe_path_lc.contains("/.antigravity/extensions/")
+        || exe_path_lc.contains("/usr/share/antigravity/resources/app/extensions/"))
+        && !exe_path_lc.contains("/antigravity/bin/language_server")
+    {
         return None;
     }
 
-    // Newer claude-code installs ship a single binary at
-    // `.local/share/claude/versions/<X.Y.Z>`, so exe basename is a version
-    // string. Detect by install-path signature first.
-    if exe_path_lc.contains("/claude/versions/") {
-        return Some(AgentKind::ClaudeCode);
+    for def in definitions {
+        for rule in &def.rules {
+            if matches_rule(rule, process, all_processes) {
+                return Some(def.kind.clone());
+            }
+        }
     }
 
-    // Direct binary names first (cheap path).
-    match exe.as_str() {
-        "claude" | "claude-code" => return Some(AgentKind::ClaudeCode),
-        "opencode" => return Some(AgentKind::OpenCode),
-        "codex" => return Some(AgentKind::Codex),
-        "gemini" => return Some(AgentKind::GeminiCli),
-        "aider" => return Some(AgentKind::Aider),
-        "copilot" => return Some(AgentKind::CopilotCli),
-        _ => {}
-    }
+    None
+}
 
-    // Node/Python wrappers: inspect argv for the package entry point.
-    if matches!(exe.as_str(), "node" | "deno" | "bun" | "python" | "python3" | "mainthread") {
-        if joined.contains("@anthropic-ai/claude-code") || joined.contains("/claude-code/") {
-            return Some(AgentKind::ClaudeCode);
+fn matches_rule(
+    rule: &AgentRule,
+    process: &ProcessSnapshot,
+    all_processes: &[ProcessSnapshot],
+) -> bool {
+    // 1. Exe basename match
+    if let Some(ref target) = rule.exe_basename {
+        if !process.exe_basename.eq_ignore_ascii_case(target)
+            && !process.process_name.eq_ignore_ascii_case(target)
+        {
+            return false;
         }
-        if joined.contains("opencode") {
-            return Some(AgentKind::OpenCode);
+    }
+
+    // 2. Exe path contains
+    if let Some(ref target) = rule.exe_path_contains {
+        if !process
+            .exe_path
+            .to_ascii_lowercase()
+            .contains(&target.to_ascii_lowercase())
+        {
+            return false;
         }
-        if joined.contains("@openai/codex") || joined.contains("codex-cli") {
-            return Some(AgentKind::Codex);
+    }
+
+    // 3. Argv contains
+    if let Some(ref targets) = rule.argv_contains {
+        let joined = process.argv.join(" ").to_ascii_lowercase();
+        for target in targets {
+            if !joined.contains(&target.to_ascii_lowercase()) {
+                return false;
+            }
         }
-        if joined.contains("@google/gemini") || joined.contains("gemini-cli") {
-            return Some(AgentKind::GeminiCli);
+    }
+
+    // 4. Exclude path contains
+    if let Some(ref target) = rule.exclude_path_contains {
+        if process
+            .exe_path
+            .to_ascii_lowercase()
+            .contains(&target.to_ascii_lowercase())
+        {
+            return false;
         }
-        if joined.contains("aider") {
-            return Some(AgentKind::Aider);
+    }
+
+    // 5. Shell parent check
+    if rule.require_shell_parent {
+        let mut parent_pid = process.ppid;
+        let mut found_shell = false;
+        // Check up to 3 levels of ancestry
+        for _ in 0..3 {
+            if let Some(ppid) = parent_pid {
+                if let Some(parent) = all_processes.iter().find(|p| p.pid == ppid) {
+                    if is_shell_process(&parent.exe_basename) {
+                        found_shell = true;
+                        break;
+                    }
+                    parent_pid = parent.ppid;
+                } else {
+                    break;
+                }
+            } else {
+                break;
+            }
         }
-        if joined.contains("copilot") || joined.contains("github-copilot") {
-            return Some(AgentKind::CopilotCli);
+        if !found_shell {
+            return false;
         }
     }
 
-    None
+    true
 }
 
 /// Snapshot of currently running agent processes.
-///
-/// Two sysinfo refreshes with a short sleep between so `cpu_usage` is meaningful
-/// (sysinfo returns 0% on first refresh of each process). The added latency
-/// (~250 ms) is acceptable given the 3 s frontend polling cadence.
-pub fn detect_running_agents() -> Vec<DetectedAgent> {
+pub fn detect_running_agents(definitions: &[AgentDefinition]) -> Vec<DetectedAgent> {
     let mut sys = System::new_with_specifics(
         RefreshKind::new().with_processes(ProcessRefreshKind::everything()),
     );
@@ -145,7 +211,8 @@ pub fn detect_running_agents() -> Vec<DetectedAgent> {
                 .exe()
                 .and_then(|p| p.file_name())
                 .map(|s| s.to_string_lossy().into_owned())
-                .unwrap_or_else(|| proc_.name().to_string_lossy().into_owned()),
+                .unwrap_or_default(),
+            process_name: proc_.name().to_string_lossy().into_owned(),
             argv: proc_
                 .cmd()
                 .iter()
@@ -155,13 +222,38 @@ pub fn detect_running_agents() -> Vec<DetectedAgent> {
             is_thread: proc_.thread_kind().is_some(),
             cpu_usage: proc_.cpu_usage(),
             ppid: proc_.parent().map(|p| p.as_u32()),
+            os_status: proc_.status(),
         })
         .collect::<Vec<_>>();
 
-    collect_detected_agents(&snapshots)
+    collect_detected_agents(&snapshots, definitions)
+}
+pub fn debug_dump_processes() -> serde_json::Value {
+    let mut sys = System::new_with_specifics(
+        RefreshKind::new().with_processes(ProcessRefreshKind::everything()),
+    );
+    sys.refresh_processes(ProcessesToUpdate::All, true);
+
+    let list: Vec<serde_json::Value> = sys
+        .processes()
+        .iter()
+        .map(|(pid, p)| {
+            serde_json::json!({
+                "pid": pid.as_u32(),
+                "name": p.name(),
+                "exe": p.exe().map(|path| path.to_string_lossy()),
+                "ppid": p.parent().map(|id| id.as_u32()),
+                "cmd": p.cmd()
+            })
+        })
+        .collect();
+    serde_json::json!(list)
 }
 
-pub fn correlate_agents_to_targets(agents: Vec<DetectedAgent>, targets: &[RepoRef]) -> Vec<DetectedAgent> {
+pub fn correlate_agents_to_targets(
+    agents: Vec<DetectedAgent>,
+    targets: &[RepoRef],
+) -> Vec<DetectedAgent> {
     agents
         .into_iter()
         .map(|mut agent| {
@@ -202,63 +294,55 @@ fn path_contains(path: &Path, base: &PathBuf) -> bool {
     path == base || path.starts_with(base)
 }
 
-fn collect_detected_agents(processes: &[ProcessSnapshot]) -> Vec<DetectedAgent> {
+fn collect_detected_agents(
+    processes: &[ProcessSnapshot],
+    definitions: &[AgentDefinition],
+) -> Vec<DetectedAgent> {
     let mut out = Vec::new();
-    for process in processes {
-        if process.is_thread {
-            continue;
-        }
-
-        // Skip threads — on Linux sysinfo includes /proc/<pid>/task/* by
-        // default, which would otherwise multiply each agent process by
-        // its thread count. `thread_kind() == None` means "real process".
-        let argv_refs: Vec<&str> = process.argv.iter().map(|s| s.as_str()).collect();
 
-        let Some(kind) = classify(&process.exe_path, &process.exe_basename, &argv_refs) else {
+    // First pass: identify all agents
+    for proc in processes {
+        if proc.is_thread {
             continue;
-        };
-
-        let pid_u32 = process.pid;
-        let display_name = format!("{} (pid {})", kind.display_name(), pid_u32);
-        let id = AgentId(format!("pid-{pid_u32}"));
-        let command_line = {
-            let s = process.argv.join(" ");
-            if s.len() > 200 {
-                format!("{}…", &s[..200])
-            } else {
-                s
+        }
+        if let Some(kind) = classify(proc, processes, definitions) {
+            let def = definitions.iter().find(|d| d.kind == kind).unwrap();
+            let mut command_line = proc.argv.join(" ");
+            if command_line.chars().count() > 200 {
+                command_line = command_line.chars().take(200).collect::<String>() + "…";
             }
-        };
-
-        out.push(DetectedAgent {
-            id,
-            kind,
-            display_name,
-            pid: pid_u32,
-            cwd: process.cwd.clone(),
-            command_line,
-            targets: AgentTargetMatches::default(),
-            status: classify_status(process.cpu_usage),
-            parent_id: None,
-        });
+            out.push(DetectedAgent {
+                id: AgentId(proc.pid.to_string()),
+                definition_id: def.id.clone(),
+                kind: kind.clone(),
+                display_name: def.display_name.clone(),
+                pid: proc.pid,
+                cwd: proc.cwd.clone(),
+                command_line,
+                targets: AgentTargetMatches::default(),
+                status: classify_status(proc.cpu_usage, proc.os_status),
+                parent_id: None, // Will populate in second pass
+            });
+        }
     }
 
-    out.sort_by(|a, b| a.pid.cmp(&b.pid));
-
-    // Second pass: any detected agent whose ppid is also a detected agent's pid
-    // is linked as a subprocess of that parent.
-    for i in 0..out.len() {
-        let ppid = processes
-            .iter()
-            .find(|p| p.pid == out[i].pid)
-            .and_then(|p| p.ppid);
-        let Some(ppid) = ppid else { continue };
-        let parent_id = out.iter().find(|a| a.pid == ppid).map(|a| a.id.clone());
-        if parent_id.is_some() {
-            out[i].parent_id = parent_id;
+    // Second pass: link parent/child relationships
+    let agent_pids: std::collections::HashSet<u32> = out.iter().map(|a| a.pid).collect();
+    for agent in &mut out {
+        let pid = agent.pid;
+        let ppid = processes.iter().find(|p| p.pid == pid).and_then(|p| p.ppid);
+
+        if let Some(ppid) = ppid {
+            // Only link direct parent/child relationships
+            if agent_pids.contains(&ppid) {
+                agent.parent_id = Some(AgentId(ppid.to_string()));
+            }
         }
     }
 
+    // Stable sort by PID
+    out.sort_by_key(|a| a.pid);
+
     out
 }
 
@@ -288,81 +372,114 @@ mod tests {
             pid,
             exe_path: exe_path.to_string(),
             exe_basename: exe_basename.to_string(),
+            process_name: exe_basename.to_string(),
             argv: argv.iter().map(|arg| arg.to_string()).collect(),
             cwd: Some("/workspace".to_string()),
             is_thread,
             cpu_usage,
             ppid: None,
+            os_status: sysinfo::ProcessStatus::Run,
+        }
+    }
+
+    fn snapshot_with_parent(
+        pid: u32,
+        ppid: Option<u32>,
+        exe_path: &str,
+        exe_basename: &str,
+        argv: &[&str],
+        is_thread: bool,
+    ) -> ProcessSnapshot {
+        ProcessSnapshot {
+            pid,
+            exe_path: exe_path.to_string(),
+            exe_basename: exe_basename.to_string(),
+            process_name: exe_basename.to_string(),
+            argv: argv.iter().map(|arg| arg.to_string()).collect(),
+            cwd: Some("/workspace".to_string()),
+            is_thread,
+            cpu_usage: 0.0,
+            ppid,
+            os_status: sysinfo::ProcessStatus::Run,
+        }
+    }
+
+    fn def_opencode() -> AgentDefinition {
+        AgentDefinition {
+            id: "opencode".into(),
+            kind: AgentKind::OpenCode,
+            display_name: "OpenCode".into(),
+            is_builtin: true,
+            rules: vec![AgentRule {
+                exe_basename: Some("opencode".into()),
+                exe_path_contains: None,
+                argv_contains: None,
+                exclude_path_contains: None,
+                require_shell_parent: false,
+            }],
         }
     }
 
     #[test]
-    fn classify_matches_supported_agent_wrappers() {
+    fn classify_matches_by_exe_basename() {
+        let defs = vec![def_opencode()];
+        let proc = snapshot(123, "/usr/bin/opencode", "opencode", &["opencode"], false);
         assert_eq!(
-            classify(
-                "/usr/bin/node",
-                "node",
-                &["node", "/tmp/@anthropic-ai/claude-code/index.js"]
-            ),
-            Some(AgentKind::ClaudeCode)
-        );
-        assert_eq!(
-            classify("/usr/bin/opencode", "opencode", &["opencode"]),
+            classify(&proc, std::slice::from_ref(&proc), &defs),
             Some(AgentKind::OpenCode)
         );
-        assert_eq!(
-            classify("/usr/bin/python3", "python3", &["python3", "-m", "aider"]),
-            Some(AgentKind::Aider)
-        );
-        assert_eq!(
-            classify("/usr/bin/copilot", "copilot", &["copilot"]),
-            Some(AgentKind::CopilotCli)
-        );
     }
 
     #[test]
-    fn classify_detects_claude_code_by_install_path() {
-        // claude-code 2.x ships a single binary at `.local/share/claude/versions/<X.Y.Z>`,
-        // so the exe basename is a version string, not "claude".
-        assert_eq!(
-            classify(
-                "/home/user/.local/share/claude/versions/2.1.139",
-                "2.1.139",
-                &["claude", "--dangerously-skip-permissions"]
-            ),
-            Some(AgentKind::ClaudeCode)
+    fn classify_respects_shell_parent_requirement() {
+        let mut def = def_opencode();
+        def.rules[0].require_shell_parent = true;
+        let defs = vec![def];
+
+        let shell = snapshot(100, "/usr/bin/zsh", "zsh", &["zsh"], false);
+        let proc = snapshot_with_parent(
+            200,
+            Some(100),
+            "/usr/bin/opencode",
+            "opencode",
+            &["opencode"],
+            false,
+        );
+        let procs = vec![shell, proc.clone()];
+
+        // Case 1: Parent is a shell
+        assert_eq!(classify(&proc, &procs, &defs), Some(AgentKind::OpenCode));
+
+        // Case 2: Parent is NOT a shell
+        let not_shell = snapshot(101, "/usr/bin/init", "init", &["init"], false);
+        let proc2 = snapshot_with_parent(
+            201,
+            Some(101),
+            "/usr/bin/opencode",
+            "opencode",
+            &["opencode"],
+            false,
         );
+        let procs2 = vec![not_shell, proc2.clone()];
+        assert_eq!(classify(&proc2, &procs2, &defs), None);
     }
 
     #[test]
     fn classify_ignores_antigravity_extensions() {
-        assert_eq!(
-            classify(
-                "/home/user/.antigravity/extensions/opencode/bin/opencode",
-                "opencode",
-                &["opencode"]
-            ),
-            None
+        let defs = vec![def_opencode()];
+        let proc = snapshot(
+            123,
+            "/home/user/.antigravity/extensions/opencode/bin/opencode",
+            "opencode",
+            &["opencode"],
+            false,
         );
-    }
-
-    #[test]
-    fn collect_detected_agents_filters_threads_and_sorts_by_pid() {
-        let agents = collect_detected_agents(&[
-            snapshot(400, "/usr/bin/opencode", "opencode", &["opencode"], false),
-            snapshot(200, "/usr/bin/node", "node", &["node", "codex-cli"], false),
-            snapshot(201, "/usr/bin/node", "node", &["node", "codex-cli"], true),
-        ]);
-
-        assert_eq!(agents.len(), 2);
-        assert_eq!(agents[0].pid, 200);
-        assert_eq!(agents[0].kind, AgentKind::Codex);
-        assert_eq!(agents[1].pid, 400);
-        assert_eq!(agents[1].kind, AgentKind::OpenCode);
+        assert_eq!(classify(&proc, std::slice::from_ref(&proc), &defs), None);
     }
 
     #[test]
     fn correlate_agents_matches_repo_and_group_from_cwd() {
+        let defs = vec![def_opencode()];
         let workspace = PathBuf::from("/workspace");
         let group = RepoRef {
             id: opencherry_core::RepoId("group:/workspace".into()),
@@ -384,16 +501,21 @@ mod tests {
         };
 
         let agents = correlate_agents_to_targets(
-            collect_detected_agents(&[ProcessSnapshot {
-                pid: 123,
-                exe_path: "/usr/bin/opencode".into(),
-                exe_basename: "opencode".into(),
-                argv: vec!["opencode".into()],
-                cwd: Some("/workspace/app/src".into()),
-                is_thread: false,
-                cpu_usage: 0.0,
-                ppid: None,
-            }]),
+            collect_detected_agents(
+                &[ProcessSnapshot {
+                    pid: 123,
+                    exe_path: "/usr/bin/opencode".into(),
+                    exe_basename: "opencode".into(),
+                    process_name: "opencode".into(),
+                    argv: vec!["opencode".into()],
+                    cwd: Some("/workspace/app/src".into()),
+                    is_thread: false,
+                    cpu_usage: 0.0,
+                    ppid: None,
+                    os_status: sysinfo::ProcessStatus::Run,
+                }],
+                &defs,
+            ),
             &[other_repo, repo.clone(), group.clone()],
         );
 
@@ -406,6 +528,7 @@ mod tests {
 
     #[test]
     fn correlate_agents_skips_targets_when_cwd_missing() {
+        let defs = vec![def_opencode()];
         let repo = RepoRef {
             id: opencherry_core::RepoId("repo:/workspace/app".into()),
             path: PathBuf::from("/workspace/app"),
@@ -414,16 +537,21 @@ mod tests {
         };
 
         let agents = correlate_agents_to_targets(
-            collect_detected_agents(&[ProcessSnapshot {
-                pid: 123,
-                exe_path: "/usr/bin/opencode".into(),
-                exe_basename: "opencode".into(),
-                argv: vec!["opencode".into()],
-                cwd: None,
-                is_thread: false,
-                cpu_usage: 0.0,
-                ppid: None,
-            }]),
+            collect_detected_agents(
+                &[ProcessSnapshot {
+                    pid: 123,
+                    exe_path: "/usr/bin/opencode".into(),
+                    exe_basename: "opencode".into(),
+                    process_name: "opencode".into(),
+                    argv: vec!["opencode".into()],
+                    cwd: None,
+                    is_thread: false,
+                    cpu_usage: 0.0,
+                    ppid: None,
+                    os_status: sysinfo::ProcessStatus::Run,
+                }],
+                &defs,
+            ),
             &[repo],
         );
 
@@ -434,22 +562,61 @@ mod tests {
 
     #[test]
     fn classify_status_returns_idle_below_threshold() {
-        assert_eq!(classify_status(0.0), AgentStatus::Idle);
-        assert_eq!(classify_status(4.9), AgentStatus::Idle);
+        assert_eq!(
+            classify_status(0.0, sysinfo::ProcessStatus::Run),
+            AgentStatus::Idle
+        );
+        assert_eq!(
+            classify_status(4.9, sysinfo::ProcessStatus::Run),
+            AgentStatus::Idle
+        );
     }
 
     #[test]
     fn classify_status_returns_generating_at_or_above_threshold() {
-        assert_eq!(classify_status(5.0), AgentStatus::Generating);
-        assert_eq!(classify_status(75.0), AgentStatus::Generating);
+        assert_eq!(
+            classify_status(5.0, sysinfo::ProcessStatus::Run),
+            AgentStatus::Generating
+        );
+        assert_eq!(
+            classify_status(75.0, sysinfo::ProcessStatus::Run),
+            AgentStatus::Generating
+        );
     }
 
     #[test]
     fn collect_detected_agents_populates_status_from_cpu_usage() {
-        let agents = collect_detected_agents(&[
-            snapshot_with_cpu(100, "/usr/bin/opencode", "opencode", &["opencode"], false, 0.1),
-            snapshot_with_cpu(200, "/usr/bin/claude", "claude", &["claude"], false, 20.0),
-        ]);
+        let defs = vec![
+            def_opencode(),
+            AgentDefinition {
+                id: "claude-code".into(),
+                kind: AgentKind::ClaudeCode,
+                display_name: "Claude Code".into(),
+                is_builtin: true,
+                rules: vec![AgentRule {
+                    exe_basename: Some("claude".into()),
+                    exe_path_contains: None,
+                    argv_contains: None,
+                    exclude_path_contains: None,
+                    require_shell_parent: false,
+                }],
+            },
+        ];
+
+        let agents = collect_detected_agents(
+            &[
+                snapshot_with_cpu(
+                    100,
+                    "/usr/bin/opencode",
+                    "opencode",
+                    &["opencode"],
+                    false,
+                    0.1,
+                ),
+                snapshot_with_cpu(200, "/usr/bin/claude", "claude", &["claude"], false, 20.0),
+            ],
+            &defs,
+        );
 
         assert_eq!(agents.len(), 2);
         assert_eq!(agents[0].pid, 100);
@@ -460,51 +627,99 @@ mod tests {
 
     #[test]
     fn collect_detected_agents_links_subprocess_to_parent() {
-        let agents = collect_detected_agents(&[
-            ProcessSnapshot {
-                pid: 100,
-                exe_path: "/usr/bin/claude".into(),
-                exe_basename: "claude".into(),
-                argv: vec!["claude".into()],
-                cwd: None,
-                is_thread: false,
-                cpu_usage: 0.0,
-                ppid: None,
-            },
-            ProcessSnapshot {
-                pid: 200,
-                exe_path: "/home/u/.local/share/claude/versions/2.1.139".into(),
-                exe_basename: "2.1.139".into(),
-                argv: vec![
-                    "/home/u/.local/share/claude/versions/2.1.139".into(),
-                    "--chrome-native-host".into(),
-                ],
-                cwd: None,
-                is_thread: false,
-                cpu_usage: 0.0,
-                ppid: Some(100),
-            },
-        ]);
+        let defs = vec![AgentDefinition {
+            id: "claude-code".into(),
+            kind: AgentKind::ClaudeCode,
+            display_name: "Claude Code".into(),
+            is_builtin: true,
+            rules: vec![
+                AgentRule {
+                    exe_basename: Some("claude".into()),
+                    exe_path_contains: None,
+                    argv_contains: None,
+                    exclude_path_contains: None,
+                    require_shell_parent: false,
+                },
+                AgentRule {
+                    exe_basename: None,
+                    exe_path_contains: Some("claude/versions/".into()),
+                    argv_contains: Some(vec!["--chrome-native-host".into()]),
+                    exclude_path_contains: None,
+                    require_shell_parent: false,
+                },
+            ],
+        }];
+
+        let agents = collect_detected_agents(
+            &[
+                ProcessSnapshot {
+                    pid: 100,
+                    exe_path: "/usr/bin/claude".into(),
+                    exe_basename: "claude".into(),
+                    process_name: "claude".into(),
+                    argv: vec!["claude".into()],
+                    cwd: None,
+                    is_thread: false,
+                    cpu_usage: 0.0,
+                    ppid: None,
+                    os_status: sysinfo::ProcessStatus::Run,
+                },
+                ProcessSnapshot {
+                    pid: 200,
+                    exe_path: "/home/u/.local/share/claude/versions/2.1.139".into(),
+                    exe_basename: "2.1.139".into(),
+                    process_name: "2.1.139".into(),
+                    argv: vec![
+                        "/home/u/.local/share/claude/versions/2.1.139".into(),
+                        "--chrome-native-host".into(),
+                    ],
+                    cwd: None,
+                    is_thread: false,
+                    cpu_usage: 0.0,
+                    ppid: Some(100),
+                    os_status: sysinfo::ProcessStatus::Run,
+                },
+            ],
+            &defs,
+        );
 
         assert_eq!(agents.len(), 2);
         assert_eq!(agents[0].pid, 100);
         assert_eq!(agents[0].parent_id, None);
         assert_eq!(agents[1].pid, 200);
-        assert_eq!(agents[1].parent_id, Some(AgentId("pid-100".into())));
+        assert_eq!(agents[1].parent_id, Some(AgentId("100".into())));
     }
 
     #[test]
     fn collect_detected_agents_parent_id_none_when_parent_not_detected() {
-        let agents = collect_detected_agents(&[ProcessSnapshot {
-            pid: 500,
-            exe_path: "/usr/bin/claude".into(),
-            exe_basename: "claude".into(),
-            argv: vec!["claude".into()],
-            cwd: None,
-            is_thread: false,
-            cpu_usage: 0.0,
-            ppid: Some(99999),
-        }]);
+        let defs = vec![AgentDefinition {
+            id: "claude-code".into(),
+            kind: AgentKind::ClaudeCode,
+            display_name: "Claude Code".into(),
+            is_builtin: true,
+            rules: vec![AgentRule {
+                exe_basename: Some("claude".into()),
+                exe_path_contains: None,
+                argv_contains: None,
+                exclude_path_contains: None,
+                require_shell_parent: false,
+            }],
+        }];
+        let agents = collect_detected_agents(
+            &[ProcessSnapshot {
+                pid: 500,
+                exe_path: "/usr/bin/claude".into(),
+                exe_basename: "claude".into(),
+                process_name: "claude".into(),
+                argv: vec!["claude".into()],
+                cwd: None,
+                is_thread: false,
+                cpu_usage: 0.0,
+                ppid: Some(99999),
+                os_status: sysinfo::ProcessStatus::Run,
+            }],
+            &defs,
+        );
 
         assert_eq!(agents.len(), 1);
         assert_eq!(agents[0].parent_id, None);
@@ -512,17 +727,23 @@ mod tests {
 
     #[test]
     fn collect_detected_agents_truncates_command_line() {
+        let defs = vec![def_opencode()];
         let long_arg = "x".repeat(250);
-        let agents = collect_detected_agents(&[ProcessSnapshot {
-            pid: 123,
-            exe_path: "/usr/bin/opencode".to_string(),
-            exe_basename: "opencode".to_string(),
-            argv: vec!["opencode".to_string(), long_arg],
-            cwd: None,
-            is_thread: false,
-            cpu_usage: 0.0,
-            ppid: None,
-        }]);
+        let agents = collect_detected_agents(
+            &[ProcessSnapshot {
+                pid: 123,
+                exe_path: "/usr/bin/opencode".to_string(),
+                exe_basename: "opencode".to_string(),
+                process_name: "opencode".to_string(),
+                argv: vec!["opencode".to_string(), long_arg],
+                cwd: None,
+                is_thread: false,
+                cpu_usage: 0.0,
+                ppid: None,
+                os_status: sysinfo::ProcessStatus::Run,
+            }],
+            &defs,
+        );
 
         assert_eq!(agents.len(), 1);
         assert!(agents[0].command_line.ends_with('…'));
diff --git a/crates/opencherry_core/src/lib.rs b/crates/opencherry_core/src/lib.rs
index b481cec..b20f406 100644
--- a/crates/opencherry_core/src/lib.rs
+++ b/crates/opencherry_core/src/lib.rs
@@ -132,23 +132,53 @@ pub enum AgentKind {
     GeminiCli,
     Aider,
     CopilotCli,
+    Custom(String),
     Unknown,
 }
 
 impl AgentKind {
-    pub fn display_name(&self) -> &'static str {
+    pub fn display_name(&self) -> String {
         match self {
-            AgentKind::ClaudeCode => "Claude Code",
-            AgentKind::OpenCode => "OpenCode",
-            AgentKind::Codex => "Codex",
-            AgentKind::GeminiCli => "Gemini CLI",
-            AgentKind::Aider => "Aider",
-            AgentKind::CopilotCli => "Copilot CLI",
-            AgentKind::Unknown => "Unknown",
+            AgentKind::ClaudeCode => "Claude Code".to_string(),
+            AgentKind::OpenCode => "OpenCode".to_string(),
+            AgentKind::Codex => "Codex".to_string(),
+            AgentKind::GeminiCli => "Gemini CLI".to_string(),
+            AgentKind::Aider => "Aider".to_string(),
+            AgentKind::CopilotCli => "Copilot CLI".to_string(),
+            AgentKind::Custom(name) => name.clone(),
+            AgentKind::Unknown => "Unknown".to_string(),
         }
     }
 }
 
+/// A rule used to detect a running agent process.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct AgentRule {
+    #[serde(default)]
+    pub exe_basename: Option<String>,
+    #[serde(default)]
+    pub exe_path_contains: Option<String>,
+    #[serde(default)]
+    pub argv_contains: Option<Vec<String>>,
+    #[serde(default)]
+    pub exclude_path_contains: Option<String>,
+    /// If true, the process's parent must be a known interactive shell.
+    #[serde(default)]
+    pub require_shell_parent: bool,
+}
+
+/// A definition for an agent that can be detected by OpenCherry.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct AgentDefinition {
+    pub id: String,
+    pub kind: AgentKind,
+    pub display_name: String,
+    pub rules: Vec<AgentRule>,
+    /// If true, this is a built-in rule that can be updated via sync.
+    #[serde(default)]
+    pub is_builtin: bool,
+}
+
 #[derive(Debug, thiserror::Error)]
 pub enum CoreError {
     #[error("path is not a git repository: {0}")]
diff --git a/crates/opencherry_persistence/Cargo.toml b/crates/opencherry_persistence/Cargo.toml
index 942faee..2e3ccac 100644
--- a/crates/opencherry_persistence/Cargo.toml
+++ b/crates/opencherry_persistence/Cargo.toml
@@ -15,3 +15,4 @@ serde_json = { workspace = true }
 anyhow = { workspace = true }
 thiserror = { workspace = true }
 tracing = { workspace = true }
+dirs = { workspace = true }
diff --git a/crates/opencherry_persistence/src/lib.rs b/crates/opencherry_persistence/src/lib.rs
index 3014c25..b37bd21 100644
--- a/crates/opencherry_persistence/src/lib.rs
+++ b/crates/opencherry_persistence/src/lib.rs
@@ -3,7 +3,7 @@
 //! SQLite-backed storage in the platform app config dir. A one-time import
 //! from the Sprint 1 `repos.json` keeps local development data intact.
 
-use opencherry_core::{Preferences, RepoId, RepoRef, Theme, TrackedTargetKind};
+use opencherry_core::{AgentDefinition, Preferences, RepoId, RepoRef, Theme, TrackedTargetKind};
 use rusqlite::{params, Connection, OptionalExtension};
 use serde::{Deserialize, Serialize};
 use std::path::{Path, PathBuf};
@@ -72,6 +72,9 @@ fn migrate(conn: &Connection) -> anyhow::Result<()> {
             json TEXT NOT NULL,
             created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
         );
+
+        DROP TABLE IF EXISTS agent_definitions;
+        DROP TRIGGER IF EXISTS agent_definitions_set_updated_at;
         "#,
     )?;
 
@@ -293,6 +296,128 @@ pub fn remove_custom_theme(config_dir: &Path, id: &str) -> anyhow::Result<bool>
     Ok(changed > 0)
 }
 
+// ---------------------------------------------------------------------------
+// Agent definitions
+// ---------------------------------------------------------------------------
+
+const DEFAULT_AGENTS_JSON: &str = include_str!("../../../resources/default_agents.json");
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+struct UserConfigSchema {
+    agents: Option<Vec<AgentDefinition>>,
+}
+
+fn resolve_config_file_path(config_dir: &Path) -> PathBuf {
+    if cfg!(test) {
+        config_dir.join("opencherry.json")
+    } else {
+        dirs::home_dir()
+            .map(|h| h.join(".opencherry").join("opencherry.json"))
+            .unwrap_or_else(|| config_dir.join("opencherry.json"))
+    }
+}
+
+fn load_user_config(config_dir: &Path) -> (PathBuf, UserConfigSchema) {
+    let path = resolve_config_file_path(config_dir);
+    if !path.exists() {
+        if let Some(parent) = path.parent() {
+            let _ = std::fs::create_dir_all(parent);
+        }
+        return (
+            path,
+            UserConfigSchema {
+                agents: Some(Vec::new()),
+            },
+        );
+    }
+
+    let content = match std::fs::read_to_string(&path) {
+        Ok(c) => c,
+        Err(_) => {
+            return (
+                path,
+                UserConfigSchema {
+                    agents: Some(Vec::new()),
+                },
+            )
+        }
+    };
+
+    let schema = serde_json::from_str(&content).unwrap_or_else(|_| UserConfigSchema {
+        agents: Some(Vec::new()),
+    });
+    (path, schema)
+}
+
+fn save_user_config(path: &Path, schema: &UserConfigSchema) -> anyhow::Result<()> {
+    let content = serde_json::to_string_pretty(schema)?;
+    std::fs::write(path, content)?;
+    Ok(())
+}
+
+/// Return all agent definitions merged from default embedded and local overrides.
+pub fn list_agent_definitions(config_dir: &Path) -> anyhow::Result<Vec<AgentDefinition>> {
+    // 1. Parse built-in rules embedded at compile-time
+    let mut defs: Vec<AgentDefinition> = serde_json::from_str(DEFAULT_AGENTS_JSON)?;
+    for d in &mut defs {
+        d.is_builtin = true;
+    }
+
+    // 2. Load and merge user-defined rules from ~/.opencherry/opencherry.json
+    let (_, schema) = load_user_config(config_dir);
+    if let Some(custom_agents) = schema.agents {
+        for mut custom in custom_agents {
+            custom.is_builtin = false;
+            // Overwrite existing or append
+            if let Some(pos) = defs.iter().position(|d| d.id == custom.id) {
+                defs[pos] = custom;
+            } else {
+                defs.push(custom);
+            }
+        }
+    }
+
+    // Stable sort
+    defs.sort_by(|a, b| {
+        b.is_builtin.cmp(&a.is_builtin).then_with(|| {
+            a.display_name
+                .to_lowercase()
+                .cmp(&b.display_name.to_lowercase())
+        })
+    });
+    Ok(defs)
+}
+
+/// Insert or replace an agent definition inside user's opencherry.json file.
+pub fn upsert_agent_definition(config_dir: &Path, def: &AgentDefinition) -> anyhow::Result<()> {
+    let (path, mut schema) = load_user_config(config_dir);
+    let mut agents = schema.agents.unwrap_or_default();
+
+    if let Some(pos) = agents.iter().position(|a| a.id == def.id) {
+        agents[pos] = def.clone();
+    } else {
+        agents.push(def.clone());
+    }
+
+    schema.agents = Some(agents);
+    save_user_config(&path, &schema)?;
+    Ok(())
+}
+
+/// Remove an agent definition by id from user's opencherry.json file.
+pub fn remove_agent_definition(config_dir: &Path, id: &str) -> anyhow::Result<bool> {
+    let (path, mut schema) = load_user_config(config_dir);
+    let mut agents = schema.agents.unwrap_or_default();
+
+    let original_len = agents.len();
+    agents.retain(|a| a.id != id);
+    let changed = agents.len() != original_len;
+
+    schema.agents = Some(agents);
+    save_user_config(&path, &schema)?;
+    Ok(changed)
+}
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -314,6 +439,7 @@ fn parse_kind(kind: &str) -> TrackedTargetKind {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use opencherry_core::{AgentKind, AgentRule};
     use std::{
         fs,
         path::{Path, PathBuf},
@@ -778,4 +904,37 @@ mod tests {
             .any(|repo| repo.display_name == "workspace-group"
                 && repo.kind == TrackedTargetKind::Group));
     }
+
+    #[test]
+    fn add_list_and_remove_agent_definitions() {
+        let dir = TestDir::new("persistence-agents");
+        let config = dir.path();
+
+        let initial_len = list_agent_definitions(config).unwrap().len();
+
+        let def = AgentDefinition {
+            id: "test-agent".into(),
+            kind: AgentKind::Custom("Test".into()),
+            display_name: "Test Agent".into(),
+            is_builtin: false,
+            rules: vec![AgentRule {
+                exe_basename: Some("test".into()),
+                exe_path_contains: None,
+                argv_contains: None,
+                exclude_path_contains: None,
+                require_shell_parent: true,
+            }],
+        };
+
+        upsert_agent_definition(config, &def).unwrap();
+        let list = list_agent_definitions(config).unwrap();
+        assert_eq!(list.len(), initial_len + 1);
+        let added = list.iter().find(|a| a.id == "test-agent").unwrap();
+        assert_eq!(added.rules.len(), 1);
+        assert!(added.rules[0].require_shell_parent);
+
+        remove_agent_definition(config, "test-agent").unwrap();
+        let list = list_agent_definitions(config).unwrap();
+        assert_eq!(list.len(), initial_len);
+    }
 }
diff --git a/crates/opencherry_repo/src/lib.rs b/crates/opencherry_repo/src/lib.rs
index 16c582d..53fab83 100644
--- a/crates/opencherry_repo/src/lib.rs
+++ b/crates/opencherry_repo/src/lib.rs
@@ -11,8 +11,8 @@ use std::{collections::HashMap, fs, path::Path, process::Command};
 
 /// Smoke-test entry point: returns the short OID of HEAD or an error.
 pub fn head_short_id(path: &Path) -> anyhow::Result<String> {
-    let repo = git2::Repository::discover(path)
-        .map_err(|_| CoreError::NotARepo(path.to_path_buf()))?;
+    let repo =
+        git2::Repository::discover(path).map_err(|_| CoreError::NotARepo(path.to_path_buf()))?;
     let head = repo.head()?;
     let oid = head
         .target()
@@ -22,8 +22,8 @@ pub fn head_short_id(path: &Path) -> anyhow::Result<String> {
 
 /// Compute a full live status snapshot for the repository at `path`.
 pub fn repo_status(path: &Path) -> anyhow::Result<RepoStatus> {
-    let repo = git2::Repository::discover(path)
-        .map_err(|_| CoreError::NotARepo(path.to_path_buf()))?;
+    let repo =
+        git2::Repository::discover(path).map_err(|_| CoreError::NotARepo(path.to_path_buf()))?;
     let workdir = repo.workdir().unwrap_or(path).to_path_buf();
     let id = RepoId::from_path(&workdir);
 
@@ -49,33 +49,29 @@ pub fn repo_status(path: &Path) -> anyhow::Result<RepoStatus> {
         .map(|s| !s.is_empty())
         .unwrap_or(false);
 
-    let (ahead, behind, upstream) = if let (Some(branch_name), Some(local_oid)) =
-        (branch.as_ref(), head_oid)
-    {
-        match repo.find_branch(branch_name, git2::BranchType::Local) {
-            Ok(local_branch) => match local_branch.upstream() {
-                Ok(upstream_branch) => {
-                    let upstream_name = upstream_branch
-                        .name()
-                        .ok()
-                        .flatten()
-                        .map(|s| s.to_string());
-                    let upstream_oid = upstream_branch.get().target();
-                    match upstream_oid {
-                        Some(up_oid) => match repo.graph_ahead_behind(local_oid, up_oid) {
-                            Ok((a, b)) => (Some(a), Some(b), upstream_name),
-                            Err(_) => (None, None, upstream_name),
-                        },
-                        None => (None, None, upstream_name),
+    let (ahead, behind, upstream) =
+        if let (Some(branch_name), Some(local_oid)) = (branch.as_ref(), head_oid) {
+            match repo.find_branch(branch_name, git2::BranchType::Local) {
+                Ok(local_branch) => match local_branch.upstream() {
+                    Ok(upstream_branch) => {
+                        let upstream_name =
+                            upstream_branch.name().ok().flatten().map(|s| s.to_string());
+                        let upstream_oid = upstream_branch.get().target();
+                        match upstream_oid {
+                            Some(up_oid) => match repo.graph_ahead_behind(local_oid, up_oid) {
+                                Ok((a, b)) => (Some(a), Some(b), upstream_name),
+                                Err(_) => (None, None, upstream_name),
+                            },
+                            None => (None, None, upstream_name),
+                        }
                     }
-                }
+                    Err(_) => (None, None, None),
+                },
                 Err(_) => (None, None, None),
-            },
-            Err(_) => (None, None, None),
-        }
-    } else {
-        (None, None, None)
-    };
+            }
+        } else {
+            (None, None, None)
+        };
 
     Ok(RepoStatus {
         id,
@@ -89,13 +85,17 @@ pub fn repo_status(path: &Path) -> anyhow::Result<RepoStatus> {
 }
 
 pub fn repo_diff(path: &Path) -> anyhow::Result<RepoDiff> {
-    let repo = git2::Repository::discover(path)
-        .map_err(|_| CoreError::NotARepo(path.to_path_buf()))?;
+    let repo =
+        git2::Repository::discover(path).map_err(|_| CoreError::NotARepo(path.to_path_buf()))?;
     let statuses = collect_statuses(&repo)?;
 
     let staged_map = diff_file_map(
         &repo,
-        repo.diff_tree_to_index(head_tree(&repo)?.as_ref(), None, Some(default_diff_options()))?,
+        repo.diff_tree_to_index(
+            head_tree(&repo)?.as_ref(),
+            None,
+            Some(default_diff_options()),
+        )?,
     )?;
     let unstaged_map = diff_file_map(
         &repo,
@@ -122,9 +122,7 @@ pub fn repo_diff(path: &Path) -> anyhow::Result<RepoDiff> {
         }
 
         if entry.untracked {
-            untracked.push(
-                unstaged_file.unwrap_or_else(|| empty_diff_file(&path, "untracked")),
-            );
+            untracked.push(unstaged_file.unwrap_or_else(|| empty_diff_file(&path, "untracked")));
             continue;
         }
 
@@ -133,9 +131,8 @@ pub fn repo_diff(path: &Path) -> anyhow::Result<RepoDiff> {
         }
 
         if entry.has_unstaged {
-            unstaged.push(
-                unstaged_file.unwrap_or_else(|| empty_diff_file(&path, &entry.status_label)),
-            );
+            unstaged
+                .push(unstaged_file.unwrap_or_else(|| empty_diff_file(&path, &entry.status_label)));
         }
     }
 
@@ -214,8 +211,8 @@ pub fn repo_group_snapshot(path: &Path) -> anyhow::Result<RepoGroupSnapshot> {
 }
 
 pub fn stage_file(path: &Path, relative_path: &str) -> anyhow::Result<()> {
-    let repo = git2::Repository::discover(path)
-        .map_err(|_| CoreError::NotARepo(path.to_path_buf()))?;
+    let repo =
+        git2::Repository::discover(path).map_err(|_| CoreError::NotARepo(path.to_path_buf()))?;
     let mut index = repo.index()?;
     index.add_all([relative_path], git2::IndexAddOption::DEFAULT, None)?;
     index.write()?;
@@ -223,8 +220,8 @@ pub fn stage_file(path: &Path, relative_path: &str) -> anyhow::Result<()> {
 }
 
 pub fn unstage_file(path: &Path, relative_path: &str) -> anyhow::Result<()> {
-    let repo = git2::Repository::discover(path)
-        .map_err(|_| CoreError::NotARepo(path.to_path_buf()))?;
+    let repo =
+        git2::Repository::discover(path).map_err(|_| CoreError::NotARepo(path.to_path_buf()))?;
     let head = repo.head()?.peel_to_commit()?;
     repo.reset_default(Some(head.as_object()), [relative_path])?;
     Ok(())
@@ -237,8 +234,8 @@ pub struct DiscardOutcome {
 }
 
 pub fn discard_files(path: &Path, relative_paths: &[&str]) -> anyhow::Result<DiscardOutcome> {
-    let repo = git2::Repository::discover(path)
-        .map_err(|_| CoreError::NotARepo(path.to_path_buf()))?;
+    let repo =
+        git2::Repository::discover(path).map_err(|_| CoreError::NotARepo(path.to_path_buf()))?;
     let workdir = repo
         .workdir()
         .ok_or_else(|| anyhow::anyhow!("repository has no working tree"))?
@@ -315,8 +312,8 @@ fn publish_branch_with<F>(path: &Path, run_git_cmd: F) -> anyhow::Result<RepoAct
 where
     F: Fn(&Path, &[&str]) -> anyhow::Result<()>,
 {
-    let repo = git2::Repository::discover(path)
-        .map_err(|_| CoreError::NotARepo(path.to_path_buf()))?;
+    let repo =
+        git2::Repository::discover(path).map_err(|_| CoreError::NotARepo(path.to_path_buf()))?;
     let head = repo.head()?;
     if !head.is_branch() {
         return Err(anyhow::anyhow!("cannot publish a detached HEAD"));
@@ -337,8 +334,8 @@ fn sync_changes_with<F>(path: &Path, run_git_cmd: F) -> anyhow::Result<RepoActio
 where
     F: Fn(&Path, &[&str]) -> anyhow::Result<()>,
 {
-    let repo = git2::Repository::discover(path)
-        .map_err(|_| CoreError::NotARepo(path.to_path_buf()))?;
+    let repo =
+        git2::Repository::discover(path).map_err(|_| CoreError::NotARepo(path.to_path_buf()))?;
     let head = repo.head()?;
     if !head.is_branch() {
         return Err(anyhow::anyhow!("cannot sync a detached HEAD"));
@@ -363,8 +360,8 @@ fn commit(path: &Path, message: &str, stage_all: bool) -> anyhow::Result<CommitR
         return Err(anyhow::anyhow!("commit message cannot be empty"));
     }
 
-    let repo = git2::Repository::discover(path)
-        .map_err(|_| CoreError::NotARepo(path.to_path_buf()))?;
+    let repo =
+        git2::Repository::discover(path).map_err(|_| CoreError::NotARepo(path.to_path_buf()))?;
     let mut index = repo.index()?;
     if stage_all {
         index.add_all(["*"], git2::IndexAddOption::DEFAULT, None)?;
@@ -424,7 +421,8 @@ fn collect_statuses(repo: &git2::Repository) -> anyhow::Result<Vec<StatusEntry>>
             .head_to_index()
             .and_then(|delta| delta.new_file().path().or_else(|| delta.old_file().path()))
             .or_else(|| {
-                entry.index_to_workdir()
+                entry
+                    .index_to_workdir()
                     .and_then(|delta| delta.new_file().path().or_else(|| delta.old_file().path()))
             })
             .map(|p| p.to_string_lossy().into_owned())
@@ -562,7 +560,11 @@ fn head_tree(repo: &git2::Repository) -> anyhow::Result<Option<git2::Tree<'_>>>
 }
 
 fn has_staged_changes(repo: &git2::Repository) -> anyhow::Result<bool> {
-    let diff = repo.diff_tree_to_index(head_tree(repo)?.as_ref(), None, Some(default_diff_options()))?;
+    let diff = repo.diff_tree_to_index(
+        head_tree(repo)?.as_ref(),
+        None,
+        Some(default_diff_options()),
+    )?;
     Ok(diff.deltas().len() > 0)
 }
 
@@ -652,12 +654,16 @@ fn delta_status_label(status: git2::Delta) -> &'static str {
 
 fn default_remote_name(repo: &git2::Repository) -> anyhow::Result<String> {
     if let Ok(head) = repo.head() {
-        if let Ok(branch) = head.resolve().and_then(|h| h.peel_to_commit()).and_then(|_| {
-            repo.find_branch(
-                head.shorthand().unwrap_or_default(),
-                git2::BranchType::Local,
-            )
-        }) {
+        if let Ok(branch) = head
+            .resolve()
+            .and_then(|h| h.peel_to_commit())
+            .and_then(|_| {
+                repo.find_branch(
+                    head.shorthand().unwrap_or_default(),
+                    git2::BranchType::Local,
+                )
+            })
+        {
             if let Ok(upstream) = branch.upstream() {
                 if let Ok(Some(name)) = upstream.name() {
                     if let Some((remote, _branch)) = name.split_once('/') {
@@ -689,7 +695,11 @@ where
     } else {
         let stderr = String::from_utf8_lossy(&output.stderr).trim().to_string();
         let stdout = String::from_utf8_lossy(&output.stdout).trim().to_string();
-        Err(anyhow::anyhow!(if !stderr.is_empty() { stderr } else { stdout }))
+        Err(anyhow::anyhow!(if !stderr.is_empty() {
+            stderr
+        } else {
+            stdout
+        }))
     }
 }
 
@@ -781,10 +791,7 @@ mod tests {
         fn append_file(&self, relative_path: &str, contents: &str) {
             let file_path = self.path.join(relative_path);
             use std::io::Write;
-            let mut file = fs::OpenOptions::new()
-                .append(true)
-                .open(file_path)
-                .unwrap();
+            let mut file = fs::OpenOptions::new().append(true).open(file_path).unwrap();
             file.write_all(contents.as_bytes()).unwrap();
         }
 
@@ -794,7 +801,9 @@ mod tests {
 
         fn commit_all_files(&self, message: &str) -> git2::Oid {
             let mut index = self.repo.index().unwrap();
-            index.add_all(["*"], git2::IndexAddOption::DEFAULT, None).unwrap();
+            index
+                .add_all(["*"], git2::IndexAddOption::DEFAULT, None)
+                .unwrap();
             index.write().unwrap();
             self.commit_index(message)
         }
@@ -823,16 +832,13 @@ mod tests {
         }
 
         fn create_branch_with_remote(&self, name: &str, remote: &str) {
-            let head_commit = self
-                .repo
-                .head()
-                .unwrap()
-                .peel_to_commit()
-                .unwrap();
+            let head_commit = self.repo.head().unwrap().peel_to_commit().unwrap();
             self.repo.branch(name, &head_commit, true).unwrap();
             self.repo.set_head(&format!("refs/heads/{name}")).unwrap();
             self.repo.checkout_head(None).unwrap();
-            self.repo.remote(remote, "https://example.com/opencherry.git").unwrap();
+            self.repo
+                .remote(remote, "https://example.com/opencherry.git")
+                .unwrap();
             self.repo
                 .reference(
                     &format!("refs/remotes/{remote}/{name}"),
@@ -846,7 +852,10 @@ mod tests {
                 .set_str(&format!("branch.{name}.remote"), remote)
                 .unwrap();
             config
-                .set_str(&format!("branch.{name}.merge"), &format!("refs/heads/{name}"))
+                .set_str(
+                    &format!("branch.{name}.merge"),
+                    &format!("refs/heads/{name}"),
+                )
                 .unwrap();
         }
     }
@@ -904,7 +913,9 @@ mod tests {
         index.add_path(Path::new("behind.txt")).unwrap();
         index.write().unwrap();
         let remote_commit = repo.commit_index("remote ahead");
-        repo.repo.reset(&head_commit.into_object(), git2::ResetType::Hard, None).unwrap();
+        repo.repo
+            .reset(&head_commit.into_object(), git2::ResetType::Hard, None)
+            .unwrap();
         repo.repo
             .reference(
                 "refs/remotes/origin/feature",
@@ -955,7 +966,8 @@ mod tests {
                 .set_str("user.email", "tests@opencherry.local")
                 .unwrap();
         }
-        seed.remote("origin", remote_path.to_str().unwrap()).unwrap();
+        seed.remote("origin", remote_path.to_str().unwrap())
+            .unwrap();
         fs::write(seed_path.join("shared.txt"), "base\n").unwrap();
         {
             let mut index = seed.index().unwrap();
@@ -967,16 +979,13 @@ mod tests {
             seed.commit(Some("HEAD"), &sig, &sig, "initial", &tree, &[])
                 .unwrap();
         }
-        let branch_name = seed
-            .head()
-            .unwrap()
-            .shorthand()
-            .unwrap()
-            .to_string();
+        let branch_name = seed.head().unwrap().shorthand().unwrap().to_string();
         seed.find_remote("origin")
             .unwrap()
             .push(
-                &[&format!("refs/heads/{branch_name}:refs/heads/{branch_name}")],
+                &[&format!(
+                    "refs/heads/{branch_name}:refs/heads/{branch_name}"
+                )],
                 None,
             )
             .unwrap();
@@ -1009,7 +1018,9 @@ mod tests {
             .find_remote("origin")
             .unwrap()
             .push(
-                &[&format!("refs/heads/{branch_name}:refs/heads/{branch_name}")],
+                &[&format!(
+                    "refs/heads/{branch_name}:refs/heads/{branch_name}"
+                )],
                 None,
             )
             .unwrap();
@@ -1068,11 +1079,8 @@ mod tests {
         repo.write_file("modified.txt", "dirty\n");
         repo.write_file("scratch.txt", "untracked\n");
 
-        let outcome = discard_files(
-            repo.path(),
-            &["modified.txt", "scratch.txt", "README.md"],
-        )
-        .unwrap();
+        let outcome =
+            discard_files(repo.path(), &["modified.txt", "scratch.txt", "README.md"]).unwrap();
 
         assert_eq!(outcome.discarded.len(), 2);
         assert!(outcome.discarded.contains(&"modified.txt".to_string()));
@@ -1094,8 +1102,7 @@ mod tests {
         repo.commit_all_files("seed real.txt");
         repo.write_file("real.txt", "dirty\n");
 
-        let outcome =
-            discard_files(repo.path(), &["real.txt", "ghost.txt"]).unwrap();
+        let outcome = discard_files(repo.path(), &["real.txt", "ghost.txt"]).unwrap();
 
         assert_eq!(outcome.discarded, vec!["real.txt".to_string()]);
         assert_eq!(outcome.failed.len(), 1);
@@ -1234,7 +1241,11 @@ mod tests {
                     "origin".to_string(),
                     "feature".to_string(),
                 ],
-                vec!["push".to_string(), "origin".to_string(), "feature".to_string()],
+                vec![
+                    "push".to_string(),
+                    "origin".to_string(),
+                    "feature".to_string()
+                ],
             ]
         );
     }
diff --git a/justfile b/justfile
new file mode 100644
index 0000000..70db0d5
--- /dev/null
+++ b/justfile
@@ -0,0 +1,34 @@
+# OpenCherry Task Runner
+
+# Setup the project dependencies
+setup:
+    ./scripts/setup.sh
+
+# Run the application in development mode
+dev:
+    pnpm -C apps/desktop tauri dev
+
+# Run all tests (Rust and Frontend)
+test: test-rust test-frontend
+
+# Run Rust tests only
+test-rust:
+    cargo test --workspace
+
+# Run Frontend tests only
+test-frontend:
+    pnpm -C apps/desktop test
+
+# Run linting and formatting checks
+check:
+    cargo fmt --all -- --check
+    cargo clippy --workspace --all-targets -- -D warnings
+    pnpm -C apps/desktop build
+
+# Build the production .deb package (Linux)
+build-deb:
+    ./scripts/build-deb.sh
+
+# List all available commands
+list:
+    @just --list
diff --git a/my_cmdline.txt b/my_cmdline.txt
new file mode 100644
index 0000000..09f94cc
Binary files /dev/null and b/my_cmdline.txt differ
diff --git a/resources/default_agents.json b/resources/default_agents.json
new file mode 100644
index 0000000..a4f70d2
--- /dev/null
+++ b/resources/default_agents.json
@@ -0,0 +1,68 @@
+[
+  {
+    "id": "claude-code",
+    "kind": "claude-code",
+    "display_name": "Claude Code",
+    "is_builtin": true,
+    "rules": [
+      {
+        "exe_basename": "claude",
+        "require_shell_parent": true
+      },
+      {
+        "exe_basename": "claude-code",
+        "require_shell_parent": true
+      },
+      {
+        "exe_basename": "node",
+        "argv_contains": ["claude"],
+        "require_shell_parent": true
+      }
+    ]
+  },
+  {
+    "id": "codex",
+    "kind": "codex",
+    "display_name": "Codex",
+    "is_builtin": true,
+    "rules": [
+      {
+        "exe_basename": "codex",
+        "require_shell_parent": true
+      },
+      {
+        "exe_basename": "node",
+        "argv_contains": ["codex"],
+        "require_shell_parent": true
+      }
+    ]
+  },
+  {
+    "id": "antigravity-cli",
+    "kind": { "custom": "Antigravity CLI" },
+    "display_name": "Antigravity CLI",
+    "is_builtin": true,
+    "rules": [
+      {
+        "exe_basename": "agy",
+        "require_shell_parent": true
+      },
+      {
+        "exe_basename": "antigravity",
+        "require_shell_parent": true
+      }
+    ]
+  },
+  {
+    "id": "opencode",
+    "kind": "open-code",
+    "display_name": "OpenCode",
+    "is_builtin": true,
+    "rules": [
+      {
+        "exe_basename": "opencode",
+        "require_shell_parent": false
+      }
+    ]
+  }
+]
diff --git a/scripts/setup.sh b/scripts/setup.sh
new file mode 100755
index 0000000..f33d6a9
--- /dev/null
+++ b/scripts/setup.sh
@@ -0,0 +1,57 @@
+#!/bin/bash
+set -e
+
+# Colors for output
+GREEN='\033[0;32m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+echo -e "${BLUE}🍒 Starting OpenCherry setup...${NC}"
+
+# 1. System Dependencies (Ubuntu/Debian)
+if command -v apt-get &> /dev/null; then
+    echo -e "${BLUE}Installing system dependencies...${NC}"
+    sudo apt-get update
+    sudo apt-get install -y \
+        libwebkit2gtk-4.1-dev \
+        libjavascriptcoregtk-4.1-dev \
+        libsoup-3.0-dev \
+        librsvg2-dev \
+        libssl-dev \
+        libayatana-appindicator3-dev \
+        build-essential \
+        curl \
+        wget
+else
+    echo -e "${BLUE}Non-Debian system detected. Please ensure you have the required Tauri dependencies installed manually.${NC}"
+fi
+
+# 2. Rust Toolchain
+if ! command -v cargo &> /dev/null; then
+    echo -e "${BLUE}Installing Rust via rustup...${NC}"
+    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
+    source "$HOME/.cargo/env"
+else
+    echo -e "${GREEN}Rust is already installed.${NC}"
+fi
+
+# 3. Node.js & pnpm
+if ! command -v node &> /dev/null; then
+    echo -e "${BLUE}Node.js not found. Please install Node.js 20+ manually.${NC}"
+    exit 1
+fi
+
+if ! command -v pnpm &> /dev/null; then
+    echo -e "${BLUE}Installing pnpm...${NC}"
+    sudo npm install -g pnpm@9
+else
+    echo -e "${GREEN}pnpm is already installed.${NC}"
+fi
+
+# 4. Project Dependencies
+echo -e "${BLUE}Installing project dependencies...${NC}"
+pnpm -C apps/desktop install
+
+echo -e "${GREEN}✅ OpenCherry setup complete!${NC}"
+echo -e "You can now run the project with: ${BLUE}pnpm -C apps/desktop tauri dev${NC}"
+echo -e "Or if you have 'just' installed, simply run: ${BLUE}just dev${NC}"