[
  {
    "id": "what-is-deputy-shell",
    "title": "What is Deputy Shell?",
    "navLabel": "What is Deputy Shell?",
    "url": "https://deputyshell.com/docs/what-is-deputy-shell/",
    "categoryId": "start-here",
    "category": "Start Here",
    "status": "available",
    "statusLabel": "Available",
    "appliesTo": "0.13.0-alpha.1 (pre-alpha)",
    "lastVerified": "2026-07-31",
    "tags": [
      "overview",
      "android terminal",
      "coding workspace"
    ],
    "hubBlurb": "What Deputy Shell is, and what it isn't.",
    "headings": [
      "What it is",
      "What it is not"
    ],
    "text": "Deputy Shell is a native Android app that gives you a terminal, project workspaces, and persistent sessions for coding-agent workflows, plus an optional integration with OpenAI's Codex CLI. It runs locally on your device: your projects, sessions, and terminal history live in the app's own storage, and network-capable tools only reach the network when their job requires it or when you tell them to.\nWhat it is\nAn Android terminal with persistent sessions you can leave and come back to.\nA project/workspace model that keeps separate codebases in separate folders.\nA curated, Android-compatible development runtime: Git, Python and pip, Node.js and npm, curl, OpenSSH tools, and ripgrep, delivered as a one-time download.\nAn optional integration with the Codex CLI, OpenAI's coding agent, for users with their own eligible OpenAI account.\nWhat it is not\nNot a cloud-hosted coding environment. Deputy Shell does not host your workspace remotely or provide its own account/cloud-storage system.\nNot \"a Deputy Shell AI model.\" Deputy Shell does not train or operate its own language model; Codex is OpenAI's product, used with your own OpenAI account.\nNot an OpenAI subscription. Deputy Shell does not sell, provide, or resell OpenAI accounts, credits, or subscriptions.\nNot a finished Android IDE or full Linux distribution. There is no integrated code editor, no Android build/APK toolchain yet, and no general package manager — see Known Limitations.\nDeputy Shell is currently pre-release (closed alpha) software, version 0.13.0-alpha.1. Every article in this Bibliothek states whether the feature it describes is available today, limited, experimental, or still planned."
  },
  {
    "id": "getting-started",
    "title": "Getting Started",
    "navLabel": "Getting Started",
    "url": "https://deputyshell.com/docs/getting-started/",
    "categoryId": "start-here",
    "category": "Start Here",
    "status": "available",
    "statusLabel": "Available",
    "appliesTo": "0.13.0-alpha.1 (pre-alpha)",
    "lastVerified": "2026-07-31",
    "tags": [
      "onboarding",
      "first run",
      "setup"
    ],
    "hubBlurb": "The real first-use sequence: setup, workspace, first session.",
    "headings": [
      "First run, step by step",
      "Safety and backups"
    ],
    "text": "On first launch, Deputy Shell downloads its development runtime, then opens on the Default Workspace with an empty session list. From there you can start working immediately or create a dedicated project first.\nDeputy Shell provides a terminal and development workspace. Commands and agents (including Codex) can modify or delete files and communicate with external services. Review actions before approving them, and keep independent backups of anything important.\nFirst run, step by step\nRuntime setup. The app downloads and verifies its development runtime (roughly 500 MB) over Google Play. See Runtime Setup for what happens during this step and how to recover from an interruption.\nChoose your privacy settings. A first-run dialog lets you choose whether to share crash reports and usage statistics, share crash reports only, or share nothing. Nothing is shared unless you choose to. See Privacy and Telemetry.\nStart in the Default Workspace, or create a project. The Default Workspace is always available and cannot be deleted. If you're working on something specific, create a named project first — see Projects and Workspaces.\nStart a session. Use \"+ New Session\" to open a terminal in the current project. Sessions keep their identity and recent output even if you leave the app.\nOptionally sign in to Codex. Codex is bundled but optional to use. Signing in requires your own eligible OpenAI account — see Codex Sign-In.\nSafety and backups\nApprove agent and command actions only after reviewing what they will do. Deputy Shell is pre-release software: keep independent backups of anything you can't afford to lose, and use workspace export regularly for anything important."
  },
  {
    "id": "requirements",
    "title": "Requirements",
    "navLabel": "Requirements",
    "url": "https://deputyshell.com/docs/requirements/",
    "categoryId": "start-here",
    "category": "Start Here",
    "status": "limited",
    "statusLabel": "Available with limitations",
    "appliesTo": "0.13.0-alpha.1 (pre-alpha)",
    "lastVerified": "2026-07-31",
    "tags": [
      "requirements",
      "android version",
      "arm64",
      "device compatibility"
    ],
    "hubBlurb": "Verified Android version, architecture, and device-validation limits.",
    "headings": [
      "Android version",
      "Architecture",
      "Physical device vs. emulator",
      "16 KB memory page-size devices",
      "Storage and network"
    ],
    "text": "Deputy Shell requires Android 14 or later on a 64-bit ARM device. It has not been broadly validated across the wide range of Android hardware, and support is expanding gradually rather than claimed for \"all Android devices.\"\nAndroid version\nMinimum: Android 14 (API level 34).\nTarget/built against: Android 16 (API level 36).\nArchitecture\nDeputy Shell currently requires a device whose primary CPU architecture is arm64-v8a (64-bit ARM). Devices with a different primary architecture are rejected with a clear \"unsupported device\" message before any runtime download starts, rather than failing partway through setup.\nPhysical device vs. emulator\nFull command execution (Git, Python, Node.js, curl, ripgrep, and Codex) has been validated on a physical Samsung Galaxy S23 Ultra running Android 14. Android emulators (which typically run on x86_64) can be used to check installation and the user interface, but they cannot run Deputy Shell's ARM64 development runtime at all — the app's own architecture check will report the device as unsupported on such an emulator.\n16 KB memory page-size devices\nNewer Android devices may use a 16 KB memory page size instead of the traditional 4 KB. Deputy Shell's packaging has been verified to meet the 16 KB alignment requirements, but it has not yet been run on a physical 16 KB-page-size device — this remains under evaluation.\nStorage and network\nExpect roughly 500 MB of download for the initial runtime setup, and more on-device space once it's extracted.\nA network connection is required for initial setup, for update checks, and for Codex. Core terminal and file features work offline once setup is complete."
  },
  {
    "id": "runtime-setup",
    "title": "Runtime Setup",
    "navLabel": "Runtime Setup",
    "url": "https://deputyshell.com/docs/runtime-setup/",
    "categoryId": "start-here",
    "category": "Start Here",
    "status": "limited",
    "statusLabel": "Available with limitations",
    "appliesTo": "0.13.0-alpha.1 (pre-alpha)",
    "lastVerified": "2026-07-31",
    "tags": [
      "runtime",
      "play feature delivery",
      "first run",
      "setup"
    ],
    "hubBlurb": "Why Deputy Shell downloads a development runtime, and what's in it.",
    "headings": [
      "Why it's downloaded separately",
      "What the runtime contains",
      "What you'll see during setup",
      "Current status",
      "Updates"
    ],
    "text": "Deputy Shell ships as a small base app and downloads its development runtime — Git, Python, Node.js, curl, OpenSSH tools, ripgrep, and the Codex CLI — the first time you launch it, using Google Play's on-demand module delivery.\nWhy it's downloaded separately\nThe full development runtime is large (roughly 500 MB compressed, over 1 GB once extracted). Rather than bundling all of it into the installable app, Deputy Shell requests it as four Play-delivered modules on first run, so the initial app download stays small.\nWhat the runtime contains\nCore module: shell and core utilities, Python, and shared runtime metadata.\nTools module: Git, curl, SSH/SCP/SFTP, ripgrep, and related command-line tools — the largest of the four modules.\nNode module: Node.js and npm.\nCodex module: the Codex CLI, built for Android.\nWhat you'll see during setup\nA full-screen setup view shows progress through distinct phases — initializing, downloading, installing, verifying, and starting the terminal — with a percentage based on completed steps, not just elapsed time. If setup fails partway, Deputy Shell shows a plain-language error with the option to retry.\nCurrent status\nThe Play-delivered download mechanism itself is implemented and has passed local testing. End-to-end delivery through a live Google Play release, including recovery from an interrupted download after a fresh install, is still under evaluation — this is one of the things closed-alpha testing is expected to confirm.\nUpdates\nAn application update or a runtime-version change can replace the runtime directory. If you've made manual changes inside the runtime yourself, expect those to be reset by an update — modifying runtime files directly is unsupported and done at your own risk."
  },
  {
    "id": "projects-and-workspaces",
    "title": "Projects and Workspaces",
    "navLabel": "Projects and Workspaces",
    "url": "https://deputyshell.com/docs/projects-and-workspaces/",
    "categoryId": "projects-workspaces",
    "category": "Projects and Workspaces",
    "status": "available",
    "statusLabel": "Available",
    "appliesTo": "0.13.0-alpha.1 (pre-alpha)",
    "lastVerified": "2026-07-31",
    "tags": [
      "projects",
      "workspaces",
      "default workspace",
      "agents.md"
    ],
    "hubBlurb": "What a workspace is, and how the Default Workspace works.",
    "headings": [
      "Default Workspace",
      "Projects and sessions",
      "Why exports are project-scoped",
      "Workspace guidance for coding agents"
    ],
    "text": "A project in Deputy Shell is a sidebar entry with its own name that points to a dedicated workspace folder on your device. Projects keep separate codebases separate: each one has its own folder, and the sessions you start \"in\" a project are grouped under it in the sidebar.\nDefault Workspace\nDeputy Shell always has a project called Default Workspace. It maps to a fixed folder and cannot be deleted — if you try, Deputy Shell keeps it and shows a message explaining that it can't be removed. It's the natural place to start if you don't need separate named projects yet.\nProjects and sessions\nSessions belong to whichever project they were created in, and are grouped by project in the sidebar. A session's actual terminal location (its working directory) is normally the project's workspace folder, but the two can drift apart if a session is moved between projects — see Workspace Mismatch Warning.\nWhy exports are project-scoped\nWorkspace export always exports one project's workspace folder — not whatever folder a session's terminal happens to be sitting in at the time. This keeps export behavior predictable even if a session has drifted from its assigned project.\nWorkspace guidance for coding agents\nDeputy Shell seeds a curated AGENTS.md into a workspace when the file is missing or still contains the retired one-line placeholder. The file explains Deputy Shell's Android/Bionic environment, workspace boundaries, available tools, credential safety, dependency rules, lifecycle constraints, and other guidance for coding agents. Existing non-placeholder AGENTS.md content is preserved, and the seeded file includes a section for project-specific instructions."
  },
  {
    "id": "managing-projects",
    "title": "Managing Projects",
    "navLabel": "Managing Projects",
    "url": "https://deputyshell.com/docs/managing-projects/",
    "categoryId": "projects-workspaces",
    "category": "Projects and Workspaces",
    "status": "available",
    "statusLabel": "Available",
    "appliesTo": "0.13.0-alpha.1 (pre-alpha)",
    "lastVerified": "2026-07-31",
    "tags": [
      "projects",
      "rename",
      "delete"
    ],
    "hubBlurb": "Create, rename, and delete projects.",
    "headings": [
      "Create a project",
      "Rename a project",
      "Delete a project"
    ],
    "text": "Create a project\nUse \"+ New Project\" from the sidebar. Deputy Shell requires an explicit, non-duplicate name — it does not auto-generate placeholder names like \"Project 1,\" so pick a name before creating one.\nRename a project\nRenaming a project changes its display name in the sidebar. There is also an optional action to rename the underlying workspace folder to match. That folder rename is blocked while the project has sessions assigned to it or while an import/export is running for that project, and it fails safely — without losing any data — if a folder with the destination name already exists.\nDelete a project\nDeleting a non-default project removes only its sidebar entry. The workspace folder and its files are not deleted — they remain on your device's storage. Any sessions that belonged to the deleted project become \"ungrouped\" and show a notice explaining that their workspace files remain on disk even though the project entry is gone. Deletion is blocked while an import or export is actively running for that project.\nThe Default Workspace cannot be deleted."
  },
  {
    "id": "importing-projects",
    "title": "Importing Projects",
    "navLabel": "Importing Projects",
    "url": "https://deputyshell.com/docs/importing-projects/",
    "categoryId": "files-import-export",
    "category": "Files, Imports and Exports",
    "status": "limited",
    "statusLabel": "Available with limitations",
    "appliesTo": "0.13.0-alpha.1 (pre-alpha)",
    "lastVerified": "2026-07-31",
    "tags": [
      "import",
      "zip",
      "document picker"
    ],
    "hubBlurb": "Import a ZIP or file into a project workspace.",
    "headings": [
      "What happens on import",
      "Path safety",
      "If Deputy Shell closes mid-import",
      "Limitations"
    ],
    "text": "From a project's menu, \"Import into this workspace\" opens Android's system document picker so you can bring an existing ZIP archive or file into that project's folder.\nWhat happens on import\nSelecting a .zip file merge-imports it: files inside the archive are added or overwritten, and files already in the workspace that aren't in the archive are left untouched.\nSelecting a non-zip file imports it as a single file into the workspace.\nIf any filenames would be overwritten, Deputy Shell scans for those conflicts first and asks you to confirm before touching any existing files.\nPath safety\nBefore extracting anything, every entry in the archive is checked: no absolute paths, no path-traversal (\"..\") segments, and no unreasonably long names are allowed. Imports are also capped in size — roughly 2,000 files, 100 MB total, and 25 MB per single file — to keep a malformed or oversized archive from causing problems.\nIf Deputy Shell closes mid-import\nImports run as a tracked, step-by-step operation. If the app is closed or crashes partway through, the next time you open Deputy Shell it automatically rolls back any partially-written files, or keeps the import if it had already finished completely — your workspace is never left half-written.\nLimitations\nOnly one import or export can run against a given project at a time; a second attempt shows a busy message.\nThe document picker isn't restricted to .zip at the file-choosing step — pick carefully.\nBack up anything important before importing over existing work."
  },
  {
    "id": "exporting-workspaces",
    "title": "Exporting Workspaces",
    "navLabel": "Exporting Workspaces",
    "url": "https://deputyshell.com/docs/exporting-workspaces/",
    "categoryId": "files-import-export",
    "category": "Files, Imports and Exports",
    "status": "limited",
    "statusLabel": "Available with limitations",
    "appliesTo": "0.13.0-alpha.1 (pre-alpha)",
    "lastVerified": "2026-07-31",
    "tags": [
      "export",
      "zip",
      "workspace"
    ],
    "hubBlurb": "Export a project as a ZIP, with privacy-focused exclusions.",
    "headings": [
      "What gets exported",
      "What's excluded, and why",
      "How export works internally",
      "Limitations"
    ],
    "text": "\"Export workspace zip,\" available from a project's menu, packages that project's workspace folder into a ZIP file at a destination you choose, using Android's document picker.\nWhat gets exported\nExport always covers the project's assigned workspace folder — not wherever a session's terminal happens to currently be, which matters if a session has been moved and shows a workspace mismatch warning.\nWhat's excluded, and why\nTo reduce the chance of accidentally sharing credentials or bulky generated files, exports leave out paths such as .git, .ssh, agent-authentication and agent-state folders, node_modules, build/output directories, .env files, and files that look like private keys or contain \"auth\" or \"token\" in their path.\nThis exclusion list reduces risk — it does not eliminate it. It matches known patterns rather than scanning file contents for secrets. Always review an exported archive yourself before sharing it with anyone.\nHow export works internally\nDeputy Shell first builds and verifies a complete ZIP in its own private storage, then copies that verified archive to the destination you picked. If that copy step is interrupted, see Export Recovery.\nLimitations\nOnly one import or export can run per project workspace at a time."
  },
  {
    "id": "export-recovery",
    "title": "Interrupted Export Recovery",
    "navLabel": "Export Recovery",
    "url": "https://deputyshell.com/docs/export-recovery/",
    "categoryId": "files-import-export",
    "category": "Files, Imports and Exports",
    "status": "limited",
    "statusLabel": "Available with limitations",
    "appliesTo": "0.13.0-alpha.1 (pre-alpha)",
    "lastVerified": "2026-07-31",
    "tags": [
      "export",
      "recovery",
      "interrupted"
    ],
    "hubBlurb": "What happens if a workspace export gets interrupted.",
    "headings": [
      "If the copy step is interrupted",
      "Current limitation"
    ],
    "text": "Deputy Shell builds and verifies a workspace export in its own private storage first, then copies that finished archive to the destination you picked — because not every Android storage provider (cloud drives especially) guarantees that a copy either fully completes or leaves no trace.\nIf the copy step is interrupted\nIf Deputy Shell is closed, crashes, or the destination copy otherwise fails to finish, the next time you open the app you'll see a \"Finish workspace export\" dialog with three choices:\nChoose another destination — retries the copy from the still-valid private archive to a new location.\nDiscard export — deletes the private archive and attempts to clean up the incomplete file at the original destination, if it's still reachable.\nLater — keeps the private archive and hides the dialog for your current session only; it reappears the next time you open the app.\nIf the private archive itself turns out to be missing, incomplete, or fails its own integrity check, \"Choose another destination\" and \"Later\" aren't offered — only Discard is available, since there's nothing valid left to retry from.\nCurrent limitation\nThis recovery flow has been validated through automated crash-simulation testing, but full manual testing across every real storage provider (different cloud-drive apps, forced app termination at different exact moments, device reboots mid-copy) is still in progress. If you hit unexpected behavior during an export, exporting to local device storage first (rather than directly to a cloud-drive provider) is the more thoroughly-tested path."
  },
  {
    "id": "sessions",
    "title": "Sessions",
    "navLabel": "Sessions",
    "url": "https://deputyshell.com/docs/sessions/",
    "categoryId": "sessions-terminal",
    "category": "Sessions and Terminal",
    "status": "available",
    "statusLabel": "Available",
    "appliesTo": "0.13.0-alpha.1 (pre-alpha)",
    "lastVerified": "2026-07-31",
    "tags": [
      "sessions",
      "terminal",
      "state"
    ],
    "hubBlurb": "How independent sessions and retained history work.",
    "headings": [
      "Session states",
      "What's retained across restarts"
    ],
    "text": "A session in Deputy Shell is an independent terminal: its own process, its own input and output, and its own retained history. You can run several sessions at once without their output mixing together, and a Codex session is simply a normal terminal session running the codex command — it has no special isolation of its own.\nSession states\nRunning — the terminal process is live.\nStopped — you (or \"Stop All\") ended the live process, but the session record, its workspace, and its recent output remain.\nNeeds resume — the process disappeared unexpectedly (for example, after the app or device restarted) and needs to be started again to continue.\nCrashed — the process exited on its own, unexpectedly.\nDeleting a session is a separate, further step from stopping one — see Managing Sessions for the distinction.\nWhat's retained across restarts\nDeputy Shell stores up to approximately 1 MB of recent terminal context per session. When that limit is exceeded, older content is trimmed and the newest portion is retained. This is a bounded recent-context buffer, not a complete or unlimited terminal transcript — and it's excluded from backups, diagnostics exports, and workspace exports. Deleting a session removes this retained context permanently."
  },
  {
    "id": "managing-sessions",
    "title": "Managing Sessions",
    "navLabel": "Managing Sessions",
    "url": "https://deputyshell.com/docs/managing-sessions/",
    "categoryId": "sessions-terminal",
    "category": "Sessions and Terminal",
    "status": "available",
    "statusLabel": "Available",
    "appliesTo": "0.13.0-alpha.1 (pre-alpha)",
    "lastVerified": "2026-07-31",
    "tags": [
      "sessions",
      "stop",
      "delete",
      "pin"
    ],
    "hubBlurb": "Rename, pin, stop, delete, and Stop All.",
    "headings": [
      "Stop vs. delete",
      "Stop All Active Sessions",
      "Pinning"
    ],
    "text": "Each session's menu in the sidebar offers: Rename, Pin/Unpin, Move (to a different project — see Moving Sessions), Stop terminal, and Delete session.\nStop vs. delete\nThese are two different, deliberately separate actions:\nStop terminal ends the live process, but keeps the session in the sidebar along with its workspace and recent output. You can come back to it later.\nDelete session permanently removes the session record and its retained history. This cannot be undone.\nStop All Active Sessions\nA single \"Stop All Active Sessions\" action (with a confirmation dialog, since it can interrupt unsaved terminal work) terminates every currently-running session at once. Each one becomes stopped, not deleted — their history and workspaces remain.\nPinning\nPinning a session keeps it visually distinguished in the sidebar so you can find it quickly among many sessions."
  },
  {
    "id": "moving-sessions",
    "title": "Moving Sessions Between Projects",
    "navLabel": "Moving Sessions",
    "url": "https://deputyshell.com/docs/moving-sessions/",
    "categoryId": "sessions-terminal",
    "category": "Sessions and Terminal",
    "status": "available",
    "statusLabel": "Available",
    "appliesTo": "0.13.0-alpha.1 (pre-alpha)",
    "lastVerified": "2026-07-31",
    "tags": [
      "sessions",
      "move",
      "projects"
    ],
    "hubBlurb": "Move a session to a different project.",
    "headings": [
      "Why that matters",
      "Deleting a project with active sessions"
    ],
    "text": "The \"Move\" action on a session's menu re-assigns which project it's grouped under in the sidebar. This only changes where the session appears in the list — it does not touch the live terminal process or change its current working directory.\nWhy that matters\nBecause moving a session is a sidebar/grouping change only, a session's terminal can end up pointed at a different folder than the project it now appears under. When that happens, Deputy Shell shows a warning on the session — see Workspace Mismatch Warning for what it looks like, what it means, and how to clear it.\nDeleting a project with active sessions\nIf you delete a project that still has sessions assigned to it, those sessions aren't deleted — they become \"ungrouped,\" with a notice explaining that the project's workspace files remain on disk even though its sidebar entry is gone. This is effectively an automatic move to an unassigned state, with the same mismatch-warning behavior as a manual move."
  },
  {
    "id": "workspace-mismatch-warning",
    "title": "Workspace Mismatch Warning",
    "navLabel": "Workspace Mismatch Warning",
    "url": "https://deputyshell.com/docs/workspace-mismatch-warning/",
    "categoryId": "sessions-terminal",
    "category": "Sessions and Terminal",
    "status": "available",
    "statusLabel": "Available",
    "appliesTo": "0.13.0-alpha.1 (pre-alpha)",
    "lastVerified": "2026-07-31",
    "tags": [
      "warning",
      "workspace",
      "cwd",
      "moved session"
    ],
    "hubBlurb": "Why a session shows 'Running outside project workspace'.",
    "headings": [
      "Why this happens",
      "What to do about it",
      "Why it matters for exports"
    ],
    "text": "If a session's live terminal is sitting in a different folder than the workspace of the project it's currently grouped under, its sidebar card shows an amber \"Running outside project workspace\" warning.\nWhy this happens\nMoving a session between projects (or deleting a project a session belonged to) only changes where the session is grouped in the sidebar — it does not change the terminal's actual current directory. If those two things disagree, Deputy Shell tells you rather than silently letting the mismatch go unnoticed.\nWhat to do about it\nTapping the warning opens a dialog showing the session's current folder and the project's actual workspace folder, along with a ready-to-copy command in the form:\ncd ~/workspace/projects/<folder>\nRun that command in the session to move its terminal to match. Once the shell reports it's in the right folder, the warning clears automatically. If you cd away again afterward, it can reappear.\nWhy it matters for exports\nWorkspace export always exports the project's assigned workspace folder, not wherever a mismatched session's terminal currently sits — so a mismatch warning is a useful sign to check you're exporting (and working in) the folder you expect."
  },
  {
    "id": "background-sessions",
    "title": "Background Sessions and Notifications",
    "navLabel": "Background Sessions",
    "url": "https://deputyshell.com/docs/background-sessions/",
    "categoryId": "sessions-terminal",
    "category": "Sessions and Terminal",
    "status": "limited",
    "statusLabel": "Available with limitations",
    "appliesTo": "0.13.0-alpha.1 (pre-alpha)",
    "lastVerified": "2026-07-31",
    "tags": [
      "background",
      "notification",
      "foreground service"
    ],
    "hubBlurb": "Notifications and limits for sessions running in the background.",
    "headings": [
      "Notification permission",
      "Limits on background survival"
    ],
    "text": "While Deputy Shell has a live session, it keeps that session running in the background using Android's foreground-service mechanism, showing an ongoing notification (for example, \"Deputy Shell session running,\" or a count when several sessions are active) with a Stop Session action.\nNotification permission\nDeputy Shell asks for notification permission once, the first time you actually have a live session — not immediately at launch, and not repeatedly. If you decline, your sessions keep running normally; you simply won't see the ongoing-session notification until you enable notifications for the app in Android's Settings. You can always come back to a running session through the app itself.\nNotification permission currently controls Deputy Shell's ongoing live-session notification. The current release does not send a separate background notification when an agent is waiting at an approval prompt.\nLimits on background survival\nAndroid and individual device manufacturers can still stop background app activity — through battery optimization, aggressive task killers, or system-level foreground-service limits. Deputy Shell does not claim sessions survive indefinitely in the background: if the system ends a session's process, that session is marked as needing resume rather than silently pretending it's still running, and its notification is removed.\nBackground reliability has so far been validated primarily on one Samsung device; behavior can vary on other manufacturers' more aggressive battery-management systems."
  },
  {
    "id": "terminal-controls",
    "title": "Terminal Controls",
    "navLabel": "Terminal Controls",
    "url": "https://deputyshell.com/docs/terminal-controls/",
    "categoryId": "sessions-terminal",
    "category": "Sessions and Terminal",
    "status": "available",
    "statusLabel": "Available",
    "appliesTo": "0.13.0-alpha.1 (pre-alpha)",
    "lastVerified": "2026-07-31",
    "tags": [
      "terminal",
      "keys",
      "touch controls"
    ],
    "hubBlurb": "The accessory key row and touch controls.",
    "headings": [
      "Current limitation"
    ],
    "text": "Deputy Shell's terminal includes a togglable two-row accessory key panel so you can reach keys a touchscreen keyboard doesn't normally offer:\nRow 1: Esc, Tab, Ctrl, Up-arrow, /, -, Alt\nRow 2: Home, End, Left-arrow, Down-arrow, Right-arrow, PgUp, PgDn\nThese cover the keys most command-line tools and terminal UIs (like editors and Codex's own interface) expect but a stock Android keyboard doesn't provide directly.\nCurrent limitation\nLong-press-to-repeat on these accessory keys (holding a key down to repeat it, the way many hardware keyboards work) is not yet available — each tap sends the key once."
  },
  {
    "id": "terminal-search-copy-scrollback",
    "title": "Terminal Search, Copy, and Scrollback",
    "navLabel": "Search, Copy & Scrollback",
    "url": "https://deputyshell.com/docs/terminal-search-copy-scrollback/",
    "categoryId": "sessions-terminal",
    "category": "Sessions and Terminal",
    "status": "limited",
    "statusLabel": "Available with limitations",
    "appliesTo": "0.13.0-alpha.1 (pre-alpha)",
    "lastVerified": "2026-07-31",
    "tags": [
      "search",
      "copy",
      "selection",
      "scrollback",
      "ansi"
    ],
    "hubBlurb": "Search, text selection, copy, and jump-to-latest.",
    "headings": [
      "Search",
      "Selecting and copying text",
      "Scrolling and jump-to-latest",
      "Terminal emulation coverage"
    ],
    "text": "Search\nA search panel lets you type a query and jump between matches in the visible and retained terminal output, with Previous/Next buttons and a \"result X of Y\" counter.\nSelecting and copying text\nA long press (about half a second) on terminal text starts word-based selection, with drag handles and a magnifier for fine adjustment, plus a floating Copy / Select-all menu. A separate action lets you copy the entire visible screen at once without entering selection mode. Tapping a detected URL (outside of selection mode) opens it in your browser.\nThis selection is line-based — it does not yet reflow semantically across resizes the way some desktop terminals do; for most copy/paste use it behaves as expected, but complex multi-line selections spanning a resize may not select exactly what you'd expect.\nScrolling and jump-to-latest\nDragging scrolls the terminal viewport. Once you've scrolled away from the bottom, output no longer auto-follows, and a floating \"jump to latest\" button appears — it changes appearance if new output has arrived while you were scrolled up. Tapping it snaps back to live output.\nTerminal emulation coverage\nThe terminal supports full-color ANSI output (16-color, 256-color, and true color), cursor movement and editing, and the alternate-screen buffer used by full-screen text apps. It does not yet fully support mouse-tracking terminal apps, clickable OSC hyperlinks, or complete bracketed-paste behavior — most command-line tools work fine, but a small minority of terminal apps that depend on those specific features may behave imperfectly."
  },
  {
    "id": "codex-on-android",
    "title": "Codex on Android",
    "navLabel": "Codex on Android",
    "url": "https://deputyshell.com/docs/codex-on-android/",
    "categoryId": "codex-agents",
    "category": "Codex and Coding Agents",
    "status": "limited",
    "statusLabel": "Available with limitations",
    "appliesTo": "0.13.0-alpha.1 (pre-alpha)",
    "lastVerified": "2026-07-31",
    "tags": [
      "codex",
      "openai",
      "coding agent",
      "android"
    ],
    "hubBlurb": "How Deputy Shell's Codex integration works, and its limits.",
    "headings": [
      "Bundled, but optional to use",
      "Account requirements",
      "Network requirements",
      "Not affiliated with OpenAI"
    ],
    "text": "Deputy Shell bundles OpenAI's Codex CLI, built to run on Android, as part of its development runtime. Codex runs as an ordinary command inside a normal terminal session — there's no separate \"Codex session\" type with different isolation from any other session.\nBundled, but optional to use\nThe Codex module downloads as part of Deputy Shell's mandatory first-run setup along with the rest of the runtime — you can't skip downloading it. Actually signing in and using Codex, however, is entirely optional: the terminal, projects, and bundled development tools all work without it.\nAccount requirements\nUsing Codex requires your own eligible OpenAI account. Deputy Shell does not provide, sell, or resell OpenAI accounts, credits, or subscriptions — availability, usage limits, and any charges are set by OpenAI and depend entirely on your own account and plan, and can change independently of Deputy Shell.\nNetwork requirements\nCodex needs live network access to OpenAI's servers for sign-in and for everything beyond basic version/help commands. When you use Codex, your prompts and any project or file content you include in a request may be sent to OpenAI — Deputy Shell does not intercept or separately store that traffic beyond keeping your local sign-in token.\nNot affiliated with OpenAI\nDeputy Shell is an independent product. It distributes Codex CLI client software; it does not operate OpenAI's hosted service, and is not affiliated with, endorsed by, or a partner of OpenAI.\nFor how to sign in, see Codex Sign-In. For how command approvals work, see Codex Approvals."
  },
  {
    "id": "codex-sign-in",
    "title": "Codex Sign-In",
    "navLabel": "Codex Sign-In",
    "url": "https://deputyshell.com/docs/codex-sign-in/",
    "categoryId": "codex-agents",
    "category": "Codex and Coding Agents",
    "status": "limited",
    "statusLabel": "Available with limitations",
    "appliesTo": "0.13.0-alpha.1 (pre-alpha)",
    "lastVerified": "2026-07-31",
    "tags": [
      "codex",
      "sign in",
      "authentication",
      "chatgpt",
      "api key"
    ],
    "hubBlurb": "Guided ChatGPT sign-in, plus manual API-key login for advanced users.",
    "headings": [
      "Guided sign-in: Sign in with ChatGPT",
      "Manual API-key login through Codex CLI"
    ],
    "text": "Deputy Shell's guided sign-in path for Codex is \"Sign in with ChatGPT\" — a device-authorization flow that hands off to your browser. Advanced users can instead authenticate with their own OpenAI API key directly through the bundled Codex CLI.\nGuided sign-in: Sign in with ChatGPT\nStarting sign-in shows a login link. Deputy Shell detects it and opens it automatically in your browser; if that doesn't happen, a tap-to-open option is shown instead.\nComplete the sign-in with your OpenAI account in the browser, the same way you would on desktop.\nReturn to Deputy Shell — the session reflects that you're signed in once the browser flow completes.\nThis flow requires your own eligible OpenAI account, and a working network connection to reach OpenAI's sign-in servers.\nBefore your first sign-in, Deputy Shell shows a disclosure explaining what information may be sent to OpenAI as part of using Codex. Read it before continuing.\nManual API-key login through Codex CLI\nAvailable through Codex CLI, with manual setup. End-to-end verified on the current release-candidate runtime. Deputy Shell's guided sign-in uses ChatGPT/device authentication. Advanced users can instead authenticate with their own OpenAI API key through the bundled Codex CLI. Deputy Shell does not currently provide a dedicated API-key settings screen for this — it's a terminal command sequence, not a tap-to-use option.\nThe bundled Codex CLI accepts the key on standard input, not as a command-line argument, so it needs to be piped in:\nexport OPENAI_API_KEY=\"your-api-key\" printenv OPENAI_API_KEY | codex login --with-api-key unset OPENAI_API_KEY codex login status codex\nSet the environment variable with your key.\nPipe it into codex login --with-api-key.\nRemove it from the environment immediately.\nConfirm with codex login status, then start Codex.\nOpenAI API usage is billed separately from ChatGPT subscriptions — check your OpenAI account's own billing before relying on this route.\nTyping the key directly (for example, in an export command) can leave it visible in retained terminal text or shell history. Avoid screenshots or sharing terminal output while it's visible, and unset the variable immediately after signing in.\nNever save the key in a project's .env file, a script, or anything you might later export or share — workspace export's exclusion rules reduce but do not eliminate the risk of a saved key leaking.\nDeputy Shell does not provide, manage, or bill for your API key. This authentication route is supplied by the bundled Codex CLI itself, not by a Deputy Shell feature."
  },
  {
    "id": "codex-approvals",
    "title": "Codex and Command Approvals",
    "navLabel": "Codex Approvals",
    "url": "https://deputyshell.com/docs/codex-approvals/",
    "categoryId": "codex-agents",
    "category": "Codex and Coding Agents",
    "status": "available",
    "statusLabel": "Available",
    "appliesTo": "0.13.0-alpha.1 (pre-alpha)",
    "lastVerified": "2026-07-31",
    "tags": [
      "approvals",
      "safety",
      "guardrails"
    ],
    "hubBlurb": "Why and when Deputy Shell asks you to approve an action.",
    "headings": [
      "What triggers an approval",
      "Where approval prompts appear",
      "What to review before approving",
      "Your responsibility"
    ],
    "text": "Before certain higher-risk shell commands run — whether you typed them yourself or an agent like Codex proposed them — Deputy Shell can require your explicit approval first.\nWhat triggers an approval\nBy default, Deputy Shell flags patterns like package installs (npm install, pip install), piping a downloaded script straight into a shell, git clone, making a file executable, running scripts, editing sensitive configuration files, and commands that could expose credentials. Deputy Shell also always blocks attempts to modify its own curated runtime tools directly (for example, trying to upgrade the bundled Node.js or Codex version from inside the terminal) — that only happens through app updates.\nWhere approval prompts appear\nApproval prompts appear inside the active Deputy Shell session, where you review and respond to them directly. The current release does not send a separate background notification alerting you that an agent is waiting for approval — if you've left the app, you'll need to return to the session to see and respond to a pending prompt.\nWhat to review before approving\nWhat the command or agent action will actually do, not just its stated intent.\nWhether it touches files or paths you didn't expect.\nWhether it will send data somewhere over the network.\nYour responsibility\nAgent-generated commands and code can be incorrect. Approving an action means you're choosing to run it — review it the way you would review a command a colleague asked you to run for them, and keep backups of anything you can't afford to lose."
  },
  {
    "id": "included-development-tools",
    "title": "Included Development Tools",
    "navLabel": "Included Development Tools",
    "url": "https://deputyshell.com/docs/included-development-tools/",
    "categoryId": "dev-tools",
    "category": "Development Tools",
    "status": "mixed",
    "statusLabel": "Mixed — see status table below",
    "appliesTo": "0.13.0-alpha.1 (pre-alpha)",
    "lastVerified": "2026-07-31",
    "tags": [
      "tools",
      "git",
      "python",
      "node",
      "ripgrep",
      "curl",
      "ssh"
    ],
    "hubBlurb": "What's bundled, what's planned, and what isn't included.",
    "headings": [
      "Included and supported",
      "Planned modular tool packs",
      "Not currently included",
      "Version pinning"
    ],
    "text": "Deputy Shell bundles a curated set of command-line development tools, built to run natively on Android, as part of its downloaded runtime.\nIncluded and supported\nTool Version Notes\nGit 2.53.0 Includes the built-in credential-store and HTTPS remote helpers.\ncurl / libcurl 8.20.0\nOpenSSH tools ssh, scp, sftp\nNode.js 22.22.2 Includes npm and npx.\nnpm 10.9.7\nPython 3.13.13 Includes pip 26.0.1.\nripgrep (rg) 14.1.1 Built without PCRE2 support — PCRE2-specific regex features are unavailable.\nvim system-provided Lightweight in-terminal editing.\nPlanned modular tool packs\njq, rsync, and nano have been evaluated but are not currently included — they're candidates for a future tool pack.\nNot currently included\nA general package manager (no apt, pkg, brew, or similar).\nFull compiler toolchains (no C/C++/Rust/clang, no make/cmake).\nArbitrary Linux-native networked command-line agents beyond Codex — see Known Limitations.\nVersion pinning\nThese tool versions are curated and pinned by Deputy Shell. Attempting to self-update any of them from inside the terminal (for example, upgrading Node.js or pip directly) is detected and blocked — new versions arrive only through app updates."
  },
  {
    "id": "git-python-node-on-android",
    "title": "Git, Python, Node.js, and More on Android",
    "navLabel": "Git, Python & Node on Android",
    "url": "https://deputyshell.com/docs/git-python-node-on-android/",
    "categoryId": "dev-tools",
    "category": "Development Tools",
    "status": "available",
    "statusLabel": "Available",
    "appliesTo": "0.13.0-alpha.1 (pre-alpha)",
    "lastVerified": "2026-07-31",
    "tags": [
      "git",
      "python",
      "pip",
      "node",
      "npm",
      "ssh",
      "curl",
      "ripgrep",
      "android"
    ],
    "hubBlurb": "How the bundled toolchain fits together in real workflows.",
    "headings": [
      "What this is good for",
      "What this isn't",
      "Working with Codex"
    ],
    "text": "Deputy Shell's development runtime brings a working command-line toolchain to Android without requiring you to assemble one yourself: Git for version control, Python with pip, Node.js with npm, curl and OpenSSH for network access, and ripgrep for fast searching across a project — see Included Development Tools for exact versions.\nWhat this is good for\nCloning and pushing with Git over HTTPS or SSH, using the same credential flows you'd use on desktop.\nRunning Python scripts and installing packages with pip for scripting, data tasks, or small tools.\nRunning Node.js tools and npm packages for JavaScript/TypeScript projects, CLIs, and build scripts that don't require native compilation.\nFetching things with curl and connecting to remote hosts with SSH/SCP/SFTP.\nSearching a project instantly with ripgrep, including from inside a Codex session.\nWhat this isn't\nDeputy Shell is not a full desktop Linux distribution. There's no general package manager, no C/C++/Rust compiler toolchain, and self-updating any of the bundled tools from inside the terminal is blocked — see Included Development Tools for the full breakdown of what's supported, planned, and not included.\nWorking with Codex\nBecause these tools live in the same terminal environment Codex runs in, Codex can call Git, ripgrep, Node.js, or Python directly as part of completing a task — subject to the same approval prompts as if you'd typed the command yourself."
  },
  {
    "id": "local-storage",
    "title": "Local Storage and Data",
    "navLabel": "Local Storage and Data",
    "url": "https://deputyshell.com/docs/local-storage/",
    "categoryId": "privacy-diagnostics",
    "category": "Privacy and Diagnostics",
    "status": "available",
    "statusLabel": "Available",
    "appliesTo": "0.13.0-alpha.1 (pre-alpha)",
    "lastVerified": "2026-07-31",
    "tags": [
      "storage",
      "local data",
      "backup"
    ],
    "hubBlurb": "What's stored locally, and what leaves the app.",
    "headings": [
      "Excluded from backup",
      "Once you export"
    ],
    "text": "By default, Deputy Shell keeps everything it creates in the app's own private Android storage: your project and workspace files, project/session names, recent terminal context, your preferences and privacy choices, and any signed-in agent credentials (such as your Codex sign-in).\nExcluded from backup\nThis app-private data is excluded from Android's automatic cloud backup and device-to-device transfer — it stays on the device unless you deliberately move it, for example with workspace export.\nOnce you export\nFiles you explicitly export (a workspace ZIP, or a diagnostics export) leave app-private storage and land at whatever destination you chose — a folder on your device, a cloud-drive app, or wherever else Android's document picker lets you save to. From that point, ordinary Android file permissions and whatever app you saved it to govern that copy, not Deputy Shell.\nFor the full legal privacy statement, see the Deputy Shell Privacy Policy."
  },
  {
    "id": "privacy-and-telemetry",
    "title": "Privacy and Telemetry",
    "navLabel": "Privacy and Telemetry",
    "url": "https://deputyshell.com/docs/privacy-and-telemetry/",
    "categoryId": "privacy-diagnostics",
    "category": "Privacy and Diagnostics",
    "status": "available",
    "statusLabel": "Available",
    "appliesTo": "0.13.0-alpha.1 (pre-alpha)",
    "lastVerified": "2026-07-31",
    "tags": [
      "privacy",
      "telemetry",
      "crash reporting",
      "analytics"
    ],
    "hubBlurb": "Crash reporting and usage statistics: both optional, off by default.",
    "headings": [
      "1. Local application data",
      "2. Optional crash and ANR reporting",
      "3. Optional, limited usage statistics",
      "4. Codex / OpenAI processing",
      "User-directed network commands"
    ],
    "text": "Deputy Shell separates four different kinds of data flow, and it's worth keeping them distinct:\n1. Local application data\nYour projects, sessions, and preferences, kept on-device — see Local Storage and Data.\n2. Optional crash and ANR reporting\nDeputy Shell can optionally report crashes and app freezes (ANRs) to help fix bugs. This is off by default. A first-run dialog lets you choose to share crashes and usage statistics, share crash reports only, or share nothing — and Settings has an independent toggle if you want to change your mind later.\n3. Optional, limited usage statistics\nDeputy Shell can optionally collect a small set of usage events (like \"app ready\" or \"session created\") to understand how the app is used. This is also off by default and controlled separately from crash reporting.\n4. Codex / OpenAI processing\nWhen you use Codex, prompts and any project content you include may be sent to OpenAI as part of that request — this is separate from Deputy Shell's own telemetry and is covered in Codex on Android.\nUser-directed network commands\nTools like Git, curl, SSH, and package installers can send data over the network when you or an agent instructs them to (for example, pushing to a remote repository) — that's the normal, expected behavior of those tools, not something Deputy Shell adds on top.\nThis page summarizes behavior that's also described in the full Deputy Shell Privacy Policy, which is the authoritative legal document — read it for complete details."
  },
  {
    "id": "diagnostics",
    "title": "Diagnostics Export",
    "navLabel": "Diagnostics",
    "url": "https://deputyshell.com/docs/diagnostics/",
    "categoryId": "privacy-diagnostics",
    "category": "Privacy and Diagnostics",
    "status": "available",
    "statusLabel": "Available",
    "appliesTo": "0.13.0-alpha.1 (pre-alpha)",
    "lastVerified": "2026-07-31",
    "tags": [
      "diagnostics",
      "support",
      "export"
    ],
    "hubBlurb": "The manual, metadata-only diagnostics export.",
    "headings": [
      "What it includes",
      "What it deliberately excludes",
      "Nothing is uploaded automatically"
    ],
    "text": "From Settings, you can create a diagnostics export — a small ZIP file intended to help troubleshoot a problem, without including your actual terminal or project content.\nWhat it includes\nA short summary file, a metadata file (app/device/runtime state), a support readme, and a note listing what was deliberately excluded.\nWhat it deliberately excludes\nDiagnostics exports are designed to leave out terminal commands and output, workspace/project source content, file paths and project names, and any credentials.\nNothing is uploaded automatically\nCreating a diagnostics export is entirely manual, and nothing is sent anywhere on its own. After it's created, Android's normal share sheet opens with support@deputyshell.com suggested as a recipient — sending it is still your choice.\nReview the export yourself before sending it. Never attach passwords, access tokens, API keys, private keys, or confidential project content to a support request."
  },
  {
    "id": "updates",
    "title": "Checking for Updates",
    "navLabel": "Updates",
    "url": "https://deputyshell.com/docs/updates/",
    "categoryId": "updates-compat",
    "category": "Updates and Compatibility",
    "status": "limited",
    "statusLabel": "Available with limitations",
    "appliesTo": "0.13.0-alpha.1 (pre-alpha)",
    "lastVerified": "2026-07-31",
    "tags": [
      "updates",
      "google play"
    ],
    "hubBlurb": "Manual and automatic update checking through Google Play.",
    "headings": [
      "Possible states",
      "What's preserved",
      "Current limitation"
    ],
    "text": "Deputy Shell checks Google Play for updates automatically each time you bring the app to the foreground, limited to roughly once every 24 hours, and you can also trigger a manual check from Settings at any time.\nPossible states\nUp to date — nothing to do.\nOffline — Deputy Shell tells you it needs a connection to check Google Play, rather than showing a generic error.\nUnavailable — shown on installs that didn't come from Google Play (for example, sideloaded builds), since there's no Play update to check.\nUpdate available / downloading / ready to restart / failed — the normal stages of an in-app update.\nWhat's preserved\nYour projects, sessions, and sign-in state are designed to survive an update — active sessions become resumable rather than being silently discarded before the update finishes restarting the app.\nCurrent limitation\nThe full real-world update path — going from one published Play version to the next on a real device — is still under evaluation as part of closed-alpha testing."
  },
  {
    "id": "troubleshooting-runtime-setup",
    "title": "Troubleshooting Runtime Setup",
    "navLabel": "Runtime Setup Issues",
    "url": "https://deputyshell.com/docs/troubleshooting-runtime-setup/",
    "categoryId": "troubleshooting",
    "category": "Troubleshooting",
    "status": "info",
    "statusLabel": "Reference",
    "appliesTo": "0.13.0-alpha.1 (pre-alpha)",
    "lastVerified": "2026-07-31",
    "tags": [
      "troubleshooting",
      "runtime",
      "setup"
    ],
    "hubBlurb": "Setup stuck, failed, or reporting an unsupported device.",
    "headings": [
      "Symptom: setup reports \"unsupported device\"",
      "Symptom: setup is stuck or very slow",
      "Symptom: setup fails with an error"
    ],
    "text": "Symptom: setup reports \"unsupported device\"\nLikely cause: your device's primary CPU architecture isn't arm64-v8a — this includes most Android emulators, which typically run x86_64. What to try: Deputy Shell currently requires a 64-bit ARM Android device; see Requirements. This isn't something a retry will fix. Data preserved: nothing was written yet — no impact on any other app data.\nSymptom: setup is stuck or very slow\nLikely cause: a slow or unstable network connection, or insufficient free storage for the runtime (roughly 500 MB download, more once extracted). What to try: check your connection, confirm you have enough free storage, and retry setup using the in-app retry option. Data preserved: any projects or sessions from before are unaffected; setup itself hasn't finished so there's nothing to lose there.\nSymptom: setup fails with an error\nWhat to try: use the in-app \"Retry\" option first. If it keeps failing, restart the app and try again. When to export diagnostics: if retries consistently fail, create a diagnostics export before contacting support — it captures setup-relevant metadata without your personal content. When to contact support: if the same failure persists after a retry and a fresh app restart, reach support@deputyshell.com with your device model, Android version, and (if you made one) your diagnostics export."
  },
  {
    "id": "troubleshooting-codex-sign-in",
    "title": "Troubleshooting Codex Sign-In",
    "navLabel": "Codex Sign-In Issues",
    "url": "https://deputyshell.com/docs/troubleshooting-codex-sign-in/",
    "categoryId": "troubleshooting",
    "category": "Troubleshooting",
    "status": "info",
    "statusLabel": "Reference",
    "appliesTo": "0.13.0-alpha.1 (pre-alpha)",
    "lastVerified": "2026-07-31",
    "tags": [
      "troubleshooting",
      "codex",
      "sign in"
    ],
    "hubBlurb": "Sign-in page won't open, or stalls after the browser step.",
    "headings": [
      "Symptom: the sign-in link doesn't open automatically",
      "Symptom: sign-in seems stuck after completing the browser step",
      "When to contact support"
    ],
    "text": "Symptom: the sign-in link doesn't open automatically\nLikely cause: the automatic browser handoff didn't trigger, or your device doesn't have a default browser configured for it. What to try: use the tap-to-open option shown alongside the link, or copy the printed URL and open it manually in your browser. Data preserved: unaffected — this doesn't touch your projects or other sessions.\nSymptom: sign-in seems stuck after completing the browser step\nLikely cause: a network interruption between your device and OpenAI's sign-in servers, or the browser step wasn't fully completed. What to try: confirm you have a working network connection, return to Deputy Shell, and try signing in again from the start. Data preserved: your projects and other sessions are unaffected regardless of Codex sign-in status.\nWhen to contact support\nIf sign-in repeatedly fails with a working network connection, create a diagnostics export (it excludes credentials and terminal content) and contact support@deputyshell.com with your device model and Android version."
  },
  {
    "id": "troubleshooting-sessions",
    "title": "Troubleshooting Sessions and Background Activity",
    "navLabel": "Session & Background Issues",
    "url": "https://deputyshell.com/docs/troubleshooting-sessions/",
    "categoryId": "troubleshooting",
    "category": "Troubleshooting",
    "status": "info",
    "statusLabel": "Reference",
    "appliesTo": "0.13.0-alpha.1 (pre-alpha)",
    "lastVerified": "2026-07-31",
    "tags": [
      "troubleshooting",
      "sessions",
      "background"
    ],
    "hubBlurb": "A session shows 'needs resume', or background sessions stop.",
    "headings": [
      "Symptom: a session shows \"needs resume\"",
      "Symptom: a background session stops unexpectedly",
      "Symptom: no ongoing notification appears for a running session",
      "When to contact support"
    ],
    "text": "Symptom: a session shows \"needs resume\"\nLikely cause: the underlying process was ended by the system — commonly after the app or device restarted, or Android reclaimed background resources. What to try: reopen the session; Deputy Shell will start a new process for it. Its workspace and recent output are unaffected. Data preserved: the session's workspace folder and recent retained output remain; only the live process needed restarting.\nSymptom: a background session stops unexpectedly\nLikely cause: Android or your device manufacturer's battery-management system ended the background process. This is more common on devices with aggressive battery optimization. What to try: check your device's battery-optimization and background-activity settings for Deputy Shell, and consider exempting it if your device offers that option. Data preserved: as above — workspace and recent context remain; the session shows as needing resume.\nSymptom: no ongoing notification appears for a running session\nLikely cause: notification permission was declined, or notifications for Deputy Shell are disabled in Android Settings. What to try: enable notifications for Deputy Shell in Android's app settings. The session itself keeps running either way — this only affects whether you see the ongoing notification.\nWhen to contact support\nIf sessions are ending unexpectedly even with battery optimization disabled for Deputy Shell, export diagnostics and reach support@deputyshell.com with your device model and manufacturer."
  },
  {
    "id": "known-limitations",
    "title": "Known Limitations",
    "navLabel": "Known Limitations",
    "url": "https://deputyshell.com/docs/known-limitations/",
    "categoryId": "limitations-roadmap",
    "category": "Limitations and Compatibility",
    "status": "mixed",
    "statusLabel": "Mixed — see status table below",
    "appliesTo": "0.13.0-alpha.1 (pre-alpha)",
    "lastVerified": "2026-07-31",
    "tags": [
      "limitations",
      "compatibility",
      "known issues"
    ],
    "hubBlurb": "Current restrictions and device-validation boundaries.",
    "headings": [
      "Current application limitations",
      "Android platform limitations",
      "Device-validation limitations",
      "Third-party service limitations"
    ],
    "text": "Deputy Shell is pre-release software. This page documents current restrictions, unsupported workflows and device-validation boundaries in the current release. For intended future direction, see the Product Roadmap. Roadmap items are not descriptions of features available in the current release.\nCurrent application limitations\nSession actions (stop, delete, move) work one session at a time — there's no bulk multi-select action yet.\nTerminal accessory keys don't yet support press-and-hold repeat.\nThe terminal doesn't yet fully support mouse-tracking apps, complete OSC hyperlink rendering, or complete bracketed paste.\nDeputy Shell does not yet send a dedicated background notification when an agent is waiting for approval.\nAndroid platform limitations\nBackground terminal sessions are subject to Android's and individual manufacturers' battery and background-activity restrictions — see Background Sessions.\nDeputy Shell requires Android 14 or later on a 64-bit ARM (arm64-v8a) device — see Requirements.\nDevice-validation limitations\nFull command execution has so far been validated on one physical Samsung device.\nDevices using the newer 16 KB memory page size pass Deputy Shell's packaging checks but haven't yet been tested on real 16 KB hardware.\nAndroid emulators (typically x86_64) can't run the ARM64 development runtime at all.\nThird-party service limitations\nCodex requires network access and your own eligible OpenAI account. Its availability, usage limits, and any charges are set by OpenAI, not Deputy Shell, and can change independently."
  },
  {
    "id": "can-deputy-shell-build-apks",
    "title": "Can Deputy Shell Build Android APKs?",
    "navLabel": "Can It Build APKs?",
    "url": "https://deputyshell.com/docs/can-deputy-shell-build-apks/",
    "categoryId": "limitations-roadmap",
    "category": "Limitations and Compatibility",
    "status": "planned",
    "statusLabel": "Planned",
    "appliesTo": "0.13.0-alpha.1 (pre-alpha)",
    "lastVerified": "2026-07-31",
    "tags": [
      "apk",
      "android build",
      "roadmap"
    ],
    "hubBlurb": "A direct answer: not yet.",
    "headings": [
      "What this means in practice",
      "Status"
    ],
    "text": "No, not in the current release. Deputy Shell currently provides an Android-first terminal and coding-agent workspace. An on-device Android build toolchain, debug APK generation, signing, export, and installation are not available today.\nWhat this means in practice\nYou can use Deputy Shell's bundled Git, Node.js, and Python to write and manage Android project source code on your device, but there is currently no bundled Android SDK, Gradle build tooling, or APK signing/installation flow inside the app. Building an Android app from a Deputy Shell workspace today means pushing your code to a machine that has the Android build toolchain, the same way you would from any other remote terminal.\nStatus\nDeputy Shell does not currently include the Android SDK, Gradle build tooling or an APK build workflow. The planned direction begins with an optional Android development pack and on-device debug APK builds. Local signing and production release workflows remain a longer-term direction because secure local key storage, backup and recovery still require further design. Direct installation from Deputy Shell is not promised as a guaranteed capability.\nSee the Android development track on the Product Roadmap for the intended direction. Roadmap items are not available in the current release. For the full current-vs-planned picture, see Known Limitations."
  }
]