Skip to content
Home
Docs/AI Chat

AI Chat

The AI Chat is the fifth page of PocketCode. It talks to the provider you connected (OpenAI, Claude, Gemini, GitHub Copilot or a custom endpoint) with your own key or sign-in, so PocketCode adds no AI fee. If you allow it, the agent reads and edits your project, runs commands and uses up to 79 tools. 5 access levels decide how much it may touch without asking, and three engines decide who answers: Chat, Swarmcode and Cortex. Auto-Iteration builds a project from a description. The chat, the tools, the approvals, artifacts, checkpoints and Auto-Iteration are free; Swarmcode, Cortex and a few agent actions are Pro, and Swarmcode and Cortex each come with a free trial: 2 Swarmcode runs and 3 Cortex missions.

What it is and how to open it

The AI Chat is not a pop-up: it is the fifth and last page of the main pager, after Home, Projects, Files and the IDE page. Everything described here (conversations, artifacts, the engines, Auto-Iteration) hangs from it.

The AI Chat page on a tablet in landscape before any provider is connected: the Conversations panel with New, Search conversations and No conversations yet, the greeting Hi! I'm your AI assistant and the card No AI service configured
First run on a tablet: the Conversations panel is docked on the left and, until you connect a provider, the chat asks you to set one up.

Ways to open it

Where you areWhat you doWhat happens
The main pagerSwipe to the fifth page. The indicator shows five dots and the last one is lit.The AI Chat page.
The command paletteRun the AI Chat command.The AI Chat page.
HomeTap the AI Assistant quick action in Quick actions.The AI Chat page.
The code editorSelect code and run Ask AI About Selection (Ctrl+I).The editor closes and the chat opens with the file path and the selection (up to 4,000 characters, in a code block) as extra context. It is not typed into the box: it travels with every following turn of that conversation and is dropped when you switch to another conversation or delete this one.
A notificationTap the notification of a finished turn, of an approval that waits for you or of a background task.The chat opens on the conversation or panel it is about. The notification never approves or rejects anything.
A linkOpen pocketcode://app/chat.The AI Chat page. pocketcode://app/chat/<text> opens it and applies <text> as extra context, like the editor does.

Before the first message

  • You need at least one provider with a key or a sign-in. Without one the page says No AI service configured and offers Set up AI services, which takes you to the key sheet in Settings. The AI providers page explains every provider, the key sheet and the model list.
  • The first time you send to a provider a dialog asks Send to <provider>?. It says that PocketCode sends your message and any code or files you attach to that third-party provider over the internet, and asks you to avoid secrets or personal data you don't want processed. The answer is remembered for that provider and that account.
  • PocketCode adds no AI fee and has no credits: you pay your provider, and the request goes from your device to it. The chat has no per-plan cap on messages, conversations or tokens.

You can't, and why

  • Open one particular conversation from the recent-chats cards of Home or from a link: they open the chat on the conversation that is already active, and pocketcode://app/chat carries no conversation id.Not yet

Screen map

One row per screen, sheet and card of the AI Chat. Each one is explained in the sections below.

ScreenHow you get thereWhat you can do
AI Chat pageFifth page of the main pager.Talk to your provider, attach files and images, add context with @, run / commands, pick the access level, the engine and the effort.
HeaderTop of the page.Change the model, open Conversations, the ● N activity chip and the Conversation menu (⋮).
Empty stateA new conversation.Start from ten shortcuts, or fix what blocks you: no provider, no network, the no-network setting.
ThreadThe middle of the page.Read replies with code, diagrams and equations; copy, retry, read aloud, report; edit your messages; pin the files the agent consulted.
ComposerBottom of the page.Type, attach, mention with @, run / commands, dictate, send, stop or queue a message.
Controls barRight above the composer.Access level chip, engine chip, Effort chip, the context radial and the active skill badge.
Model selectorTap the model name in the header.Choose provider and model. It is described on the AI providers page.
Decision, approval, secret and question cardsAbove the composer, when the agent needs you.Approve or reject tool requests, allow or deny what leaves your device, give a secret, answer questions.
File changes barAbove the composer, after the agent edited files.Keep or Undo each file, or Keep all / Undo all.
ConversationsHeader button; a docked panel on wide tablets.Create, search, pin, rename, export, delete, turn a conversation into a Cortex agent.
Artifacts and the artifact viewer⋮ → Artifacts, or the Artifact card in the thread.Preview, Code and Changes tabs; version bar; Save to project, Share, Ask for changes, Open in Designer.
Files⋮ → Files.See the files the AI read or changed in this conversation and open one in the editor.
Transcript⋮ → Transcript.Read and copy what was said, without tools or cards.
Activity⋮ → Activity, or the ● N chip.See what needs you, what runs and what finished today; Review, Stop, Open, Dismiss, Stop all.
Background tasksActivity → open a terminal process.Stop commands the AI left running and clear the finished ones.
Context and usageTap the radial in the controls bar.See the context window, compress now, set auto-compress, turn reply suggestions on or off, read your provider quota.
Swarmcode card and Agent roomEngine chip → Swarmcode; then See the agents.Follow the phases of a run and change the model of the agents that haven't started.
Cortex screensEngine chip → Cortex.Welcome, the Cortex screen with the agent strip, the Agents catalogue, the agent editor, Autonomy and Mission work.
Auto-Iteration and Iteration SettingsType /loop; the gear opens the settings.Describe a project, review the plan, run it task by task, and tune 30 settings.
Pro wallsOnce the free trials are used up, choose Swarmcode or enter Cortex without a plan.Pro AI or Cortex sheet with Unlock Pro AI and Continue with basic plan.

The chat screen

This is the page itself. The sections follow the screen from top to bottom: the header, the empty state, the thread, the composer, the @ and / menus and the controls bar.

Header

The top bar shows which model answers and what the chat knows about your project.

You can

  • Tap the model name (the Change model control, with a ⇅ icon) to open the model selector. It has Recent, Favorites and All tabs and a Search all models box; the AI providers page describes it.
  • Read, under the name, the conversation title or the context: project, open file and its language, the number of files and Code loaded; No active project when there is none.
  • Tap Conversations to open the conversations sheet.
  • Tap the ● N chip to open Activity. It exists only while something runs or waits, and it turns red when something waits for you.
  • Open the Conversation menu (⋮): Artifacts, Files, Activity and Transcript.

You can't, and why

  • Find an icon for Cortex or Auto-Iteration in the header: Cortex is entered from the engine chip and Auto-Iteration with the /loop command.By design
  • Find a quota gauge in the header: the quota moved into the Context and usage sheet.By design

Empty state and shortcuts

A new conversation shows a greeting (Hi! I'm your AI assistant) and, when a provider is ready and you are online, ten shortcuts under Try with:. Each shortcut writes its prompt, sets the access level the job needs and, if it has one, turns on a skill.

The ten shortcuts

ShortcutAccess level it setsSkill it turns on
Explain codeRead onlynone
Find bugsRead only/debug
SuggestionsRead only/review
OptimizeRead only/refactor
DocumentAuto-editnone
Write testsAuto-edit/test
LearnNo tools/learn
SQL queryRead only/sql
Git helpRead only/git
AskNo toolsnone

You can

  • Tap a shortcut: the prompt appears in the box, the access level in the table below is set and the skill is turned on. Nothing is sent until you press send.
  • Tap the card that replaces the shortcuts when something blocks you: Set up AI services opens the key sheet, See the setting opens the no-network setting, Check again looks for the network again.

You can't, and why

  • Use the shortcuts with no provider, with the no-network setting on (Nothing leaves this device) or offline (There is no connection): they are hidden until the cause is fixed, because a shortcut that is going to fail is worse than none.By design

The thread and the messages

Replies stream in as the model writes. Code, diagrams and tool calls are drawn, not shown as raw text.

You can

  • Read Markdown with highlighted code blocks. A block fenced as mermaid draws a diagram, math, latex or tex an equation and chart a chart; when a Mermaid type or a chart can't be drawn, the block stays as code. html and svg blocks show a live preview once the reply has finished, with an Open in canvas button; xml blocks of any length and any other block with 15 or more line breaks get the same button.
  • Images the model links from the internet are not loaded on their own: you see a notice (“External image from … We haven't loaded it”) and Load image. Images that point outside the open project, use an address type the app doesn't open or arrive while the no-network setting is on stay blocked.
  • Under each AI message: Copy, Retry, Read aloud (and Stop reading, with Android's text-to-speech), Report and More, which shows when it was sent, the model and the tokens (with “~” and “(est.)” when the number is an estimate).
  • Under each of your messages: Edit (see Changes, checkpoints and errors).
  • Fold the reasoning (Thinking…) and the groups of tool calls (Show tool calls), and tap Show the whole reply to skip the gradual reveal.
  • Pin a file the agent consulted with Pin to the context. Pinned files appear in a strip (Files pinned to the context) with Unpin and Clear, up to 8 of them, and each one travels with every turn.
  • Read long conversations in windows: the last 50 messages load first and Show N earlier messages loads more. Scroll to bottom jumps back down.
  • Use the reply suggestions under each reply, or tap Dismiss suggestions. They can be switched off in Context and usage and cost one short request per turn.

You can't, and why

  • Edit a message and keep what came after it: editing restores the conversation to that point and removes the later messages.By design
  • Get an attached image back when you reopen a conversation: only a note that an image was attached is kept, never its bytes.By design

The composer

The box at the bottom takes text, attachments, mentions and commands.

You can

  • Type in the box (Ask anything… or Write a message…). What you were typing survives a screen rotation.
  • Tap the + button (Attach file) for @file — Project file, Image and Document. Remove drops an attachment before you send.
  • Attach up to 5 files per message. Text and code files (up to 500 KB, the first 4,000 characters are read) travel inside the prompt; a file that turns out to be binary loses its content. Images (up to 25 MB) are resized to 1,568 px on the long side, recompressed and sent as images when the model can see them. The chip of each image shows its estimated cost (~N tok).
  • Dictate with the microphone button (Start voice input / Stop voice input). The first time a notice explains that PocketCode uses the microphone only when you tap it and that Android's speech recognition processes the audio; then Android asks for the microphone permission.
  • Press Send. While the agent works the button becomes Stop generation, and you can write the next instruction and press Queue message: with providers whose loop PocketCode controls, the agent receives it in its next round without cancelling the turn; otherwise it is sent when the turn ends.
  • Stop with Stop generation: what was already generated is kept and the summary says Stopped by you.

You can't, and why

  • Send a PDF or any other binary file: the picker accepts it, but the chip says not sent because there is no reader for it. Paste the text instead.Not yet
  • Attach more than 5 files to one message: the sixth is ignored without a message.By design
  • Attach text or code over 500 KB (File is too large (max 500 KB)) or an image over 25 MB.By design
  • Send images with GitHub Copilot, with OpenAI signed in with ChatGPT or Codex, or with a model that can't see them (<model> cannot see images. Switch model or remove the image.).​By design
  • Dictate without the microphone permission, without a speech service on the device, without internet, or in a language Android has no speech pack for: each case shows its own message.Device

Add context with @

Type @ in the box and a menu offers 8 commands. Each one adds a block of context to that message; keep typing to filter them.

CommandWhat it adds to the message
@file Current fileThe content of the open file, cut to its first 4,000 characters.
@project Project treeA list of file paths, up to 100 in the message (the list itself comes from the 50-file scan described below).
@problems ProblemsThe current errors and warnings from the diagnostics. If there are none, the message says no diagnostics are available.
@terminal TerminalThe last terminal output.
@codebase CodebaseA semantic search of your project: the 5 best matches, 800 characters each.
@web <url> WebThe text of the page. Up to 3 addresses per message.
@diff Git diffYour uncommitted changes: up to 30 files, 20,000 characters in all and 6,000 per file.
@folder <path> FolderThe files of a folder: up to 3 folders, 25 files each, 4,000 characters per file and 24,000 in all. Files over 256 KB are skipped.

The file picker and its 50-file limit

  • The picker has a Search project files… box. The search is fuzzy, over names and paths, and shows up to 15 results. A file you pick is read whole if it weighs under 512,000 bytes; otherwise it is replaced by a short note, and in both cases it competes with the rest of the context for room.
  • The picker and @folder only look at the first 50 files the app finds: it walks the project in alphabetical order, keeps code and text extensions and skips hidden folders, .git, .gradle, build, node_modules, __pycache__, .idea and .vscode. In a large project the rest of your files are not offered.

You can

  • Pick a command from the menu, or type it in full. You can use several in one message.
  • Use @file — Project file (from the + menu) to pick any file of the project by name.

You can't, and why

  • Use @selection: it was removed because only the old in-editor chat could fill it. To ask about a selection, use Ask AI About Selection in the editor.By design
  • Get results from @codebase when the semantic search finds nothing: the message carries “search results not available” instead.By design
  • See more than the first 50 files of a big project in the file picker or in @folder.​By design

Commands, skills and your own prompts with /

Type / as the very first character of the box and a menu lists commands, skills and your own prompts. It opens only while the box holds nothing but a / word (no space or line break yet), so a path like /usr/bin in the middle of a message never triggers it. There is no / button.

CommandWhat it does
/helpList every available command. Shows them grouped as General, Conversation, Memory, Skills, Context and Custom prompts.
/newStart a new conversation.
/loopOpen autonomous auto-iteration. Opens Auto-Iteration.
/remember key = valueStore a project memory. Saves a note the agent reads in every turn of this project.
/forget keyRemove a stored memory.
/memoryShow stored project memories.
/skillsList available skills.
/skill-offDeactivate the active skill.
/compactCompress the conversation context. Summarises the older turns to free room.

The eight built-in skills

Typing a skill command activates it for the following turns. Skill names and descriptions are fixed English text in every language.

CommandSkill (as the app names it)
/debugDebug: expert debugger, focused on finding and fixing bugs.
/refactorRefactor: code refactoring specialist, cleaner and more maintainable code.
/sqlSQL Expert: database and SQL specialist.
/gitGit: version control expert.
/deployDeploy: deployment and DevOps specialist.
/learnLearn: teaching mode, explains concepts step by step.
/reviewCode Review: finds issues and suggests improvements.
/testTesting: writes and improves tests.

Your own agents, modes and prompts

  • Every .md file in .pocketcode/agents/ or .pocketcode/chatmodes/ of the project (and the ones installed from the Marketplace, which are global for your account) becomes a skill with the command /<file name>. The front matter can set name, description, icon, command, model, provider, tools, skills, language and scope; the body of the file is the system prompt. Cortex's agent editor writes these files for you.
  • Every .md file in .pocketcode/prompts/ (and the ones installed from the Marketplace) is a command /<file name>. Its front matter can set a description, and ${input} or {{input}} in the body is replaced by what you type after the command.
  • When two names collide, your prompt wins over a skill and a skill wins over a built-in command.

You can

  • Type / and a prefix to filter; if nothing matches by prefix the menu falls back to a fuzzy search.
  • Run a command, activate a skill (its badge appears in the controls bar with an ✕ to remove it) or run one of your prompts. Text after a skill command is sent right away as your message.

You can't, and why

  • Use a skill to change what the agent is allowed to do: a skill only changes the system prompt, never the permissions.By design

The controls bar

Right above the composer, from left to right: the active skill badge (if any), the access chip, the engine chip, the Effort chip (only when the model has levels) and, pinned on the right, the context radial.

You can

  • Tap the access chip to choose how much the agent may do (see Engines and access levels).
  • Tap the engine chip to choose Chat or Swarmcode. Cortex › is in the same menu, after a separator, because it opens a screen of its own.
  • Tap the Effort chip to choose how hard the model thinks. Each level has a one-line description from the provider (in English).
  • Read the radial: it is in the primary colour below 75 % of the context window, orange from 75 % and red from 90 %. When the model's limit isn't reliable it draws an empty ring and the tokens used with “~” instead of an invented percentage. Tap it to open Context and usage.

You can't, and why

  • See the Effort chip with a model that has no reasoning levels (Claude Haiku, gpt-4o, gpt-4.1, Gemini before 2.5): the chip is hidden.Third party
  • Use the old Ask, Plan and Agent selector: it was replaced by the access levels and the engines.By design

Effort levels by provider

The chip shows the levels of the active model. The lists are fixed in the app, except the OpenAI one: PocketCode reads it from the bundled Codex CLI when it is installed and falls back to a built-in list otherwise.

Claude (not Haiku)Off, Low, Medium, High (the default), Extra high and Max. Haiku has no levels.
OpenAI (reasoning models)From the Codex CLI, or the built-in list none, minimal, low, medium, high, xhigh. none shows as Off and minimal only exists for the gpt-5 family. gpt-4o and gpt-4.1 have no levels.
Gemini 2.5 and laterOff (not on Pro models), Low, Medium (the default), High and Max.
GitHub CopilotWhatever the wrapped model has: minimal to high for gpt-5 and the o-series, the Claude ladder for Opus and Sonnet, and Off to High for Gemini 2.5 and later.
Custom endpointNo levels offered by the app.

Engines and access levels

Two choices in the controls bar are independent: the access level says how much the agent may touch, and the engine says who answers. What older versions of the app called Ask, Plan and Agent mode is now a combination of the two.

There is no Agent mode switch. The agent works with tools whenever the access level is Ask first or higher and the engine is Chat; Read only lets it read and search; No tools keeps it to text.

The five access levels

LevelWhat the app saysWhat the agent does
No toolsText only, doesn't read filesIt gets no tools: every call is refused.
Read onlyReads and searches, changes nothingReads and searches. Anything that writes, runs or changes something is refused, not asked. The catalogue drops to 56 tools.
Ask firstAsks before writing or runningReads freely. Writing a file, running a command, deploying or any other change waits for your OK.
Auto-editWrites alone, asks before runningAlso writes files on its own (a snapshot per file is kept, so you can undo). Commands and deploys still wait for your OK.
Full accessAsks only to go off-device or to memoryEverything local runs without asking. It still asks for what leaves your device and for writes to the project memory.

A new install starts on Auto-edit. If you had chosen a level before, it is kept, and after a restart the app never raises the level on its own. The shortcuts of the empty state set their own level when you tap them. The level applies to every path the agent can take (direct API calls, the Codex CLI and the Copilot language server): they all go through the same gate.

The engines and Auto-Iteration

ChoiceWhat the app saysWhat it does and what it costs
ChatOne agent, step by step with youFree. One model, its tools and this thread.
SwarmcodeSeveral agents try, judges pick the bestPro, with 2 free runs. A lead model decides how many read-only agents to launch, runs them in parallel, synthesises their drafts and, if verification is on, has a panel of judges check the answer.
CortexNamed agents on several frontsPro, with 3 free missions. It splits a job between your agents, each with the context of its own topic, and brings the answers back together. It has screens of its own.
Auto-Iteration (not an engine)Open autonomous auto-iterationFree. Opened with /loop. It builds a project from a description, plan first, then task by task.

You can't, and why

  • Choose Swarmcode without a plan once the 2 free runs are used: the Pro AI sheet opens with You have used your free Swarmcode runs. Upgrade to keep running agent teams. (Unlock Pro AI or Continue with basic plan) and the engine doesn't change. A saved Swarmcode engine is checked again when you send, in case you lost the plan or used up the free runs.Pro
  • Enter Cortex without a plan once the 3 free missions are used: you get Cortex is part of Pro. Your free missions are used up. and the Cortex sheet.Pro

What the agent can do

When the access level allows it, the agent works through tools: it reads and searches your project, edits files, runs commands, queries databases, drives the Dev Browser and more. The app declares 84 tools. A normal chat offers up to 79 of them; the other 5 only exist inside a Cortex mission. With Read only the agent is offered 56, the ones that change nothing. These counts exclude the Workflows tools, the Workflows you marked as available to the AI and the tools of your MCP servers.

The tools by category

CategoryTools in a normal chat
Read-only (16)read_file, list_dir, file_search, grep_search, semantic_search, repo_map, get_errors, get_changed_files, build_list_tasks, project_list, color_info, color_palette, contrast_check, encode_decode, generate_hash, generate_uuid.
Questions (2)ask_user asks you a question with options; secrets asks you for a secret without ever seeing it.
Write (6)create_file, replace_string_in_file (a list of changes in one call), delete_file, rename_file, apply_patch and artifact.
Terminal (3)run_in_terminal, build_run_file, build_run_task.
Todo (1)manage_todo_list keeps the Agent tasks list you see in the thread.
Memory (1)copilot_memory stores, recalls, lists and deletes project memories.
Design (2)design_export, design_list.
Deploy (8)deploy_trigger, backend_status, backend_list_projects, backend_logs, backend_env (variable names only, never values), backend_rollback, plus the two envelopes backend_list and backend_do.
Database (6)db_query, db_execute, db_schema, db_list_tables, db_list_connections, db_inspect.
API (3)api_request, api_list_collections, api_import_curl.
SSH (4)ssh_exec, ssh_list_hosts, ssh_upload, ssh_download.
Git (7)git_status, git_commit (stages everything and commits in one step), git_log, git_diff, git_push, git_pull and git_branch (list, create or check out).
Browser (20)The 19 browser_* tools (navigate, page info, click, type, scroll, wait, find text, screenshot, console, network, storage, cookies, device profile, performance, audit and more) plus fetch_webpage. They work on the Dev Browser, which has to be open: otherwise the tool answers “Dev Browser is not open. Ask the user to open the Dev Browser, then call this tool again.”
Workflows (not counted)workflow__list, workflow__get, workflow__runs, workflow__create, workflow__update, workflow__run, plus every workflow you marked as available to the AI.
Cortex coordination (5, only in a mission)cortex_peers, cortex_recent, cortex_decisions, cortex_escalate, cortex_handoff.

These 15 categories are the rows of AI Tool Permissions (Settings → AI), where you can allow or deny each tool for a provider or for one model; a denied tool never runs, whatever the access level. The counts are for the full catalogue: ssh_exec and ssh_list_hosts are offered only when you have a saved host, api_request and api_list_collections only when you have API Tester collections, and deploy_trigger, the backend_* tools and the two envelopes only when a hosting provider is connected. The tools of your MCP servers (Settings → AI → MCP Servers) come on top.

Limits worth knowing

  • run_in_terminal runs in POSIX sh (the BusyBox ash the app bundles), not bash. A command waits 30 s by default and 120 s at most. Long output keeps its first 120 and last 120 lines and names a file with all of it. A command started in background mode keeps running and shows in Activity.
  • read_file refuses files over 5 MB and, for a long file, says from which line to continue. Searches return at most 100 results (50 by default). list_dir goes at most 5 levels deep and lists up to 500 entries.
  • A turn may take as many rounds of tool calls as the model needs: with the providers PocketCode talks to directly there is no cap by default, and the context window bounds the work (the turn ends with a summary before it overflows). You can set a cap of up to 100 rounds per provider in the provider settings. Only the fallback path for models without native tool calls stops after 10 rounds.
  • With a small context window (about 16K tokens or less) the chat declares only ten entries: eight core tools plus two that discover the rest. A custom model that can't call tools natively gets the catalogue as text instead.
  • Shell commands are classified by the damage they could do before they run. A catastrophic one (it would destroy the app's or your data, or hand over your credentials) never runs, whatever the access level and whatever the justification. This is defence in depth, not a sandbox.

Rules on top of the access level

  • What leaves your device always asks. git_push, deploy_trigger, api_request, ssh_exec, ssh_upload, browser_navigate, fetch_webpage, browser_evaluate_js, db_execute and the shell commands that publish or send something wait for your OK at every level, Full access included, unless you switch off Ask before acting outside this device (Settings → AI → AI Tool Permissions; it is on by default).
  • Writing to the project memory always asks (copilot_memory store and delete), even with Full access, because the text is read back into every later turn.
  • git_commit, git_pull, git_branch, browser_clear_storage, browser_set_cookie and secrets change something without a card, so the agent doesn't ask on every commit, but Read only and No tools do refuse them.
  • A tool you denied in AI Tool Permissions doesn't run, whatever the level, and neither do its aliases.
  • If the agent insists on the same call with the same arguments, a card asks you instead of letting it loop (It keeps asking for … with the same arguments instead of moving on).

Tool requests and Copilot cards

These cards sit above the composer, one at a time, with a badge such as “1 of 3”; the composer says how many are waiting.

You can

  • Tool Requests (for models that can't call tools natively, whose requests arrive as text blocks): it shows the Command (editable), what the model says it is for (Stated by the model), a WRITES mark and the buttons Approve, Reject, Run edited and, with several waiting, Approve all. If you change the command, Edited — the corrected command runs, and its risk is re-checked appears, and Restore the original undoes your edit. A command you empty can't be approved.
  • Copilot wants to run a tool (GitHub Copilot only): it shows the Tool and its Input with Allow and Deny.
  • Apply Copilot edits? (GitHub Copilot only): one row per file (N edits) with Apply edits and Reject edits.

You can't, and why

  • Dismiss a decision by swiping it away: these are cards, not sheets, so a gesture can't decide without confirmation.By design

Approvals: what needs your OK

With Ask first (every write and command), Auto-edit (commands) and, at every level, for what leaves your device, the agent parks the request in an approvals queue and carries on with other work: it never freezes waiting for you. The action doesn't run until you decide. Approving a local action (a file write, a command) runs it; approving something that leaves your device lets the agent's next identical request through.

You can

  • Read a folded row, “<action in plain words> · needs your OK”. Tap Show details to see why (for example “It runs commands on another machine”, “It publishes commits to the remote repository, where they cannot be taken back” or “It deploys to an environment other people can see”) and the detail in monospace.
  • Choose Deny, Allow or, for local actions such as a file write or a command, Always allow this: it is remembered only for that exact action and only for the rest of the session. It is never offered for what leaves your device or for writes to the project memory, which are looked at one at a time.
  • With several waiting, select them and use Allow selected or Turn down selected.
  • If the turn already ended, your decision reaches the agent with your next message (These are from the turn before. Your agent will hear about them with your next message.).
  • With the app in the background, a notification opens the conversation with the card in view.

You can't, and why

  • Approve or reject from a notification: it only opens the conversation.By design
  • Approve in a batch what leaves your device (Actions that leave your device are decided one at a time, so they stay here.).​By design
  • Approve while another app draws over PocketCode: the card ignores taps while it is covered (tapjacking protection).By design

Secrets: a key the agent never sees

The secrets tool lets the agent ask you for a token or an API key without ever seeing it.

You can

  • Fill the card The assistant needs a secret: Value (4 to 16,384 characters, on one line) and Hosts it may be sent to (separated by commas, https:// only; empty means terminal commands only, which always ask first). Then Save, or Decline.
  • Read the promise on the card: What you type here is encrypted on this device. The assistant never sees it and it is not saved in the chat.
  • Answer a delete request (Delete a stored secret?) with Keep or Delete; it cannot be recovered.
  • Stored secrets are masked in tool output, in conversation exports and in what is sent to the provider. A command that uses one gets its own card (It gives the command the stored secret … which it could send anywhere), even if you switched off the approvals for external actions.

You can't, and why

  • See or export a stored value: the app has no function that returns it, not even partly. Manage the list in Settings → AI → Secrets.​By design

Questions from the agent and the task list

The agent can stop to ask you something, and it keeps a visible task list.

You can

  • Answer a question card in the thread (ask_user): tap an option, Other (Or write your own answer), Skip, Next or Send. It is a card, not a dialog, and it can be folded.
  • Follow the Agent tasks card (manage_todo_list): it shows progress such as “2 / 5 done · 1 in progress” or All tasks done, with Collapse tasks, Expand tasks and Hide tasks.

You can't, and why

—

Artifacts

An artifact is a page, diagram, document or component the AI makes with the artifact tool instead of pasting it into the thread. It shows up as an Artifact card; every change creates a new version and all versions are kept.

The six artifact types

TypeWhat the viewer shows
htmlA live page in a hardened view.
svgThe image, also shareable as SVG or PNG.
mermaid (Mermaid diagram)The diagram. A Mermaid type that can't be drawn shows its source with “This kind of diagram can't be drawn here.”
markdown (Markdown document)The rendered document.
react (React component)A JSX or TSX component mounted with a bundled Preact, without network. Only react, react-dom, preact and htm can be imported.
codeSource code in any language, in the Code tab.

The artifacts list

⋮ → Artifacts lists every artifact of the whole conversation, not only the last 50 messages, with all their versions.

You can

  • Read each row: title, type, version, In your project or In the chat, and how long ago. Tap one to open the viewer.
  • With none yet it says Ask for a page or a diagram.

You can't, and why

  • Create artifacts with Read only or No tools, or inside a Cortex mission: the artifact tool writes, so it is hidden there.By design
  • Keep an artifact on disk without an open project: with no project folder the tool returns no version or path. The viewer still shows it from the thread.By design

The artifact viewer

On a tablet at least 840 dp wide the viewer is a side panel of the thread; on a phone it is full screen. You open it from the list, from the Artifact card or from the Open in canvas button of a code block.

You can

  • Switch between Preview, Code and, with two or more versions, Changes v1→v2 (a diff of up to 400 lines). The version bar (Version N of M) moves between versions.
  • Copy the code. Share as a .ext file, an SVG image or a PNG image (always as a file). Ask for changes closes the viewer and puts Change the artifact “<title>”: in the box. Open in Designer is offered for HTML and SVG, with the note Layout may change.
  • Close it with Close artifact.

You can't, and why

  • Load anything from the internet in an artifact (Runs offline. It can't load anything from the internet.): the view blocks the network, never navigates inside itself, asks before opening a link outside PocketCode and has no access to camera, microphone or location, because the HTML is written by the model and could be injected.By design
  • Save an artifact over 256 KiB per version: the tool refuses it.By design
  • Rewrite a version: versions are append-only, they don't enter checkpoints, and the folder .pocketcode/artifacts/<id>/ ignores itself in your Git.By design

Save to project and share

Save to project turns an artifact into a file you keep.

You can

  • Pick a File name (subfolders like docs/page.html are fine), a Format (Source (.ext), SVG image or PNG image) and Where to save: In the open project or Choose a location… (the system document picker). Without an open project only the second is offered.
  • Read the checks as you type, such as “Use a path inside the project, without “..” or a leading slash.” or “That folder is reserved (.git and .pocketcode).”. If the name already exists the dialog says “A file with that name already exists in the project. Saving will replace it.” and offers Replace.
  • On success you see Saved to the project: <path>.

You can't, and why

  • Save inside .git or .pocketcode, or outside the project, with In the open project: the dialog refuses the path.By design
Reviewing the changes the agent makes to your files is a different thing: see Changes, checkpoints and errors. The sheet that previews a change before you apply it belongs to the AI actions of the editor, not to the chat, and the card that asks before applying Copilot's workspace edits (Apply Copilot edits?) is described under What the agent can do.

Conversations

Every conversation is stored on your device with the provider and the model that wrote each message, so one thread can mix providers. Reopening a conversation restores its provider and exact model when that provider is configured; if the model no longer exists a notice says so and you choose another, because the chat doesn't pick one for you. With Cloud Sync (Pro) the conversations updated in the last 180 days are uploaded to your account (see Privacy and security).

The Conversations sheet

On a phone the sheet rises over the chat. In a wide tablet window, outside Cortex, it stays docked as a 320 dp panel that you can fold with Collapse panel. The subtitle (N · local & CLI) counts your local conversations plus the sessions of the Codex CLI.

You can

  • New creates a conversation, like /new.
  • Type in Search conversations…: titles and last messages filter at once, and from 2 characters it also searches inside the message bodies.
  • Read the sections Active, Pinned and Recent. Each row shows provider, model, N msgs, how long ago and Active or Finished.
  • Open the Actions menu of a row: Pin / Unpin, Rename (in place), Export (Markdown), Export (HTML page), Export (JSON), Turn into an agent / Stop being an agent (for Cortex) and Delete, which asks Delete conversation? (This action cannot be undone.).
  • A conversation takes its title from your first message, locally and at no cost (up to six words). AI titles (Settings → AI, off by default) can ask the model for a better one, which spends tokens and never overwrites a title you typed yourself.
  • Sessions of the Codex CLI (when you use it) appear in the same list, and you can open and delete them.

You can't, and why

  • Archive a conversation: the chat has pin, rename, delete and export, but no archive.Not yet
  • Rename, delete or even see Cortex's own conversation here: it is hidden, because it is the notebook of the mode.By design
  • Pin, rename or export the Codex CLI sessions: from those you can only open and delete.By design
  • Get a deleted conversation back.By design

Export formats

FormatWhat you get
Export (Markdown)The system share sheet gets the text when it is under 256 KiB, and a .md file otherwise.
Export (HTML page)A self-contained page without scripts or remote resources, always as a .html file.
Export (JSON)schemaVersion, exportedAt, the conversation (id, title, createdAt, updatedAt, messageCount, isPinned) and, per message, id, role, content, timestamp and isError. No tool calls, no reasoning, no file changes.
All threeStored secrets and key-like patterns are masked before anything is exported. Hidden and tool messages are left out of Markdown and HTML.

Files and Transcript

Two more entries of the ⋮ menu look at the whole conversation.

You can

  • Files lists the files the AI read or changed (N files · M modified). Tap one to open it in the editor.
  • Transcript shows What was said, without tools or cards, with You and Assistant, and a Copy button.

You can't, and why

—

Activity and background tasks

Long work keeps going when you leave the chat. Activity gathers what runs, what waits for you and what ended today, from the chat, Swarmcode, Cortex, AI Office, Workflows and terminal processes.

The Activity panel

Open it from ⋮ → Activity, from the ● N chip, or by tapping the service notification when two or more jobs run.

You can

  • Read three groups: Needs you · N, Running · N and Finished today · N. Each row shows its kind (Swarmcode, Cortex, AI Office, Workflow, a conversation or a terminal process), the time, ~N tokens (est.) and a state such as Waiting for approval, Waiting for your answer, Failed, Done or Stopped.
  • Use Review, Stop, Open and Dismiss on a row. Stop all asks for a second tap (Tap again to stop N). Open on an AI Office or Workflow row takes you to that screen.
  • With nothing to show it says Nothing running. Long tasks you leave running show up here.

You can't, and why

  • Open another conversation from a row while a reply is running: Finish or stop the current reply to open another conversation.​By design

Working while you are away

If you send the app to the background while a chat turn (or a Swarmcode run) is working, PocketCode starts a foreground service so the work continues.

You can

  • Read its notification, Working: <conversation> (The AI keeps working while you are away. Tap to open the conversation.). The service stops when the turn ends and releases its wake locks.
  • Get a notification when a turn finishes, fails or asks for approval, only while the app is in the background. Tapping it opens the conversation.
  • If the system refuses to start the service, the panel marks the work Not protected in background.

You can't, and why

  • Keep a turn alive after you remove the app from recents: that destroys the chat's view model and the turn with it.Device

Background tasks

Commands the AI started in the background (servers, watchers) are listed here.

You can

  • Open the sheet from Activity by opening a terminal-process row.
  • Read each row: the command and running for 3 min, finished, finished with code N or stopped by you.
  • Stop one task, or Clear finished. With none it says The AI has not left anything running in the background.

You can't, and why

—

Context and usage

The radial in the controls bar opens a sheet with two clocks: This conversation (what fills the model's window, which empties when you compress) and Your account (the quota your provider reports, which resets on its own schedule).

The Context and usage sheet

Tap the radial, or See usage on a quota notice.

You can

  • Read the percentage of the context window and tokens in the window. When the model's limit is unknown it says tokens in the context window (the model limit is unknown) and shows no fraction.
  • Read spent in this conversation and read from cache, when the provider reports them.
  • See the split Tool results and files, Messages and Instructions and tools only when the provider reports it (today, the GitHub Copilot language server); it is never guessed.
  • Tap Compress now: it summarises the older turns and frees room, and nothing is deleted. The sheet shows the estimated cost (~N tokens from the active provider) and says Not enough messages to compress yet. when there is too little.
  • Switch Auto-compress at 85% (on by default): the app summarises the older turns by itself when the window reaches 85 %, spending tokens of your provider each time. /compact does the same on demand.
  • Switch Reply suggestions (on by default): chips after each reply, one short request per turn.
  • Read your provider quota and tap Refresh: Last 5 h, Weekly, Last 7 days or Last 30 days, with a countdown (resets in …); for GitHub Copilot Premium, Chat and Completions. Claude and ChatGPT report their windows with the answers, so send a message first.

You can't, and why

  • See your spending in money: with your own key the app doesn't know your rate, so it shows tokens and provider windows, never a price.Third party
  • See your Gemini quota: Google does not publicly expose the remaining quota. The sheet shows your email and a link to the AI Studio dashboard.Third party
  • See the Codex limits of a ChatGPT Free plan: only paid plans (Plus, Pro, Team, Enterprise) expose them.Third party
  • Keep the quota numbers after you restart the app: they live in memory.By design

How tokens are counted

  • A number with “~” and “(est.)” is an estimate made on your device; a number without them came from the provider. The estimate counts 4 characters per token for Latin writing and 1 token per CJK character, rounded up.
  • Swarmcode, Cortex, Activity and Auto-Iteration show their tokens as “~N tokens (est.)” for the same reason, whenever the provider doesn't report usage.
  • The chat shows tokens and provider windows, never a price.

Swarmcode

Swarmcode is the Pro engine for hard questions. A lead model decides how many agents the job needs, the agents work in parallel, a synthesis merges their drafts and a panel of judges checks the answer before you see it. Pick it in the engine chip: Swarmcode carries a PRO tag while you have neither the plan nor free runs left. Without the plan you get 2 free runs as a trial, and during it the chip shows N free runs left instead of the tag. A run is counted when it ends having delivered a finished draft or finding, per account and with no clock; failed runs, cancelled plans and stops before anything finished don't count, and stopping at the budget pause counts once something was delivered. The offer has a remote switch, so if it is turned off Swarmcode is Pro only. When the runs are used up you see You have used your free Swarmcode runs. Upgrade to keep running agent teams.

What a run does

  1. 1Plan: the lead decides how many agents are needed (Deciding how many agents are needed), from 1 up to the attempts of your Intensity.
  2. 2Work: the agents run in parallel up to the concurrency limit, and the rest wait. They are read-only: they can read files and look at database schemas and table lists, nothing else.
  3. 3Verify: a panel of independent judges scores the synthesised answer. If too few accept it, it is revised and judged again until it passes or the review rounds run out. With Second opinion from another provider on (it is off by default), one judge runs on another provider you have connected.
  4. 4Apply: only the Build mission does it. One single agent writes the verified answer to your project files, only inside the project and through the same write path as the chat. The other three missions answer and leave your files alone. With No tools or Read only access the applier is not launched, even in Build.

Defaults and ranges

Setting (Settings → AI → Swarmcode)Default and range
Intensity: Quick2 attempts, 1 judge, up to 1 review round
Intensity: Balanced3 attempts, 3 judges, up to 2 review rounds. The default
Intensity: Thorough5 attempts, 3 judges, up to 3 review rounds
Budget per run~200K tokens (est.) by default. One tap: 100K, 200K or 400K. Custom: 0 to 500K in steps of 10K, where 0 is No limit
Second opinion from another providerOff

Changes are a draft until you tap Apply changes, and they count from the next run. The attempts are a ceiling: the lead uses as many as the task needs. The missions are not in that sheet. You pick one in the engine chip menu, under Mission: Review (find problems), Bug hunt (chase one bug), Investigate (answers, no edits) and Build (competing versions). Review is the default. Opening the settings sheet is free; using Swarmcode is Pro, apart from 2 free runs. The AI providers page describes the sheet.

The Swarmcode card in the thread

While a run works, the thread shows a Swarmcode card.

You can

  • Follow the phases Plan, Work, Verify and Apply and the state (Planning, Working, Verifying, Applying, Done, Failed or Stopped), with a counter such as “~N / M tokens (est.)”.
  • Read the verdict of the judges, for example 2 of 3 judges accepted it.
  • Tap See the agents to open the Agent room.
  • Leave the app: the run keeps working in the background, with the notification Swarmcode keeps working while you are away.

You can't, and why

  • Use Swarmcode on the Free plan beyond its 2 free runs.Pro
  • Let the agents write to your project by themselves: the parallel agents are read-only. Only the Build mission has a single applier write the verified answer, and not under No tools or Read only access.By design
  • Get tools for the agents with GitHub Copilot: every Swarmcode call goes in Copilot's text-only Ask mode.By design

The Agent room

A sheet that lists the agents of the run.

You can

  • Read the capacity bar Whole run and the groups In flight, Waiting and Finished.
  • See each agent (Agent N) with its provider, model and Effort, and the marks On start and Re-aimed by the lead. Under What it did an agent that has finished shows its conclusion; one that failed shows the reason instead.
  • Edit the provider, model and effort of an agent that hasn't sent its request, or use Change them all for every agent still waiting.

You can't, and why

  • Change the model of an agent in flight: It already sent its request, so its model can't change midway. What you touch is saved for the next turn.​By design
  • Read what an agent did inside: What an agent does inside isn't recorded yet.​Not yet

Swarmcode Hive (in testing)

The build we are testing adds a second flavor to Swarmcode. You pick it in the same engine chip, under Flavor. Everything described above is the Adversarial flavor: one question, the best answer. Hive is for a big task you want done end to end.

Hive is not in the published app yet. This section describes the build under test, and details can still change before it ships.
AdversarialHive
Good forOne question, the best answerA big task, done end to end
How it worksA few drafts of the same thing, and judges that try to knock them downA planner splits the task into phases and agents made to measure, an engine runs them, and the planner wraps up
How many agentsUp to 2, 3 or 5, depending on the Intensity (Quick, Balanced or Thorough) in Swarmcode settingsAs many as the task needs, up to 200 per run
Who writes filesOnly the Build mission: one applier agent, after the judgesEach agent that has write access, without stepping on each other
LookTeal, with the usual Swarmcode iconOrange, with a honeycomb icon

How a Hive run goes

  1. 1Tap the engine chip, choose Swarmcode, then Hive under Flavor. The mission row only shows with Adversarial.
  2. 2Describe the task. The planner, which runs on your Strong model, reads the session and the project, then hands the app a plan: phases, and in each phase the agents with their brief, their files and the model tier they need.
  3. 3The app checks the plan before spending anything more: unique ids, no cycles, at most 200 agents and 20 phases, files inside the project, and tools never above your chat's access level. If something is wrong the planner gets the errors once to fix them. If it fails again, the turn ends and says why.
  4. 4The Hive block appears in the chat and the run starts by itself, with no approval step. Phases run in the order of their dependencies and four agents work at once. If the provider answers with a rate limit, the app lowers that number by itself and raises it again as requests succeed. Two agents that declare the same file never run at the same time.
  5. 5Each agent ends with a short report in a fixed shape. The app collects the reports into a summary and saves each agent's full output in its own file, in .pocketcode/hive/<run>/ inside your project. That folder has its own .gitignore, so it stays out of Git.
  6. 6The planner reads the summary, checks what it needs and answers you. It can start one more run to fix what came out wrong, with two runs as the most in one turn.

Model tiers

  • Hive, Adversarial, Cortex, AI Office and AI Designer hand out work by tier instead of using whatever model the chat has. You set the tiers in Settings → AI → Model tiers: Strong plans, wraps up and decides, Medium does the work (reads, edits, researches) and Cheap does the mechanical checks (remove duplicates, verify, summarize).
  • You pick one model per tier. The same model can fill all three, and a free model works for Cheap.
  • The first time you open one of those modules with no tiers set, a one-tap screen suggests three models built from the ones you already use. Use these saves them. Your normal chat keeps its own model.
  • In Hive the planner uses Strong and the plan gives each agent a tier. The planner never picks a specific model.

Cost and the free run

  • Settings → AI → Hive budget sets the most tokens one Hive message may use. The default is ~2M tokens (est.). You can choose from ~500K to ~10M, or remove the ceiling after a confirmation.
  • Hive pauses once, when it reaches the ceiling, and asks before going on. Agents already running finish first, so the final count can go a little over. With no ceiling it never pauses because of cost.
  • The block header shows an estimate such as “~N tokens expected (est.)”. Hive shows tokens, never a price, and they are spent on your own key.
  • Models with low request limits, like the free ones on OpenRouter, make a run slower, because the app waits out the rate limits. With a local server Hive runs one agent at a time.
  • Hive is part of Pro. Without Pro you get one free Hive run. Once it is used, choosing Hive, or sending a message with Hive selected, opens the Pro screen before anything starts.
  • The free run has a ceiling of ~500K tokens (est.), and the lower of that and your Hive budget applies. It allows one run per message, so the planner's second run is Pro only.
  • The free run is counted when the run starts. If you stop and discard the run with the chat still open, before any agent has started or spent a token, the free run comes back.
  • In the flavor menu, the Hive row shows 1 free run or PRO.

Pausing, saving and undoing

  • The run is saved on your phone as it goes. Pause run stops new agents from starting while the ones working finish their task. Resume carries on, and nothing already done is repeated.
  • It also pauses by itself when the connection drops (it picks up when you are back online, and no agent is marked as failed), when the provider's quota runs out, when it reaches the ceiling, and when the app is closed or killed. Open the app and resume.
  • Agents that were working when the app died start again, after the app undoes what they left half written.
  • In the block's menu, Undo the run puts the project back as it was before the run: it reverts only what the run changed and keeps what you edited afterwards. Stop and discard stops the agents for good, and the files they already wrote stay as they are.
  • Agents work at your chat's access level and go through the same gates as a normal turn: the path cage, the veto on destructive commands, the network gate and the secrets filter. Each agent has read, write or full tools (full includes the terminal), never above that level, so with Read only access no agent can write. A confirmation card for something destructive stops only that agent.
  • The saved run goes away with its conversation, and after 30 days without changes.

You can

  • Follow the phases on a vertical timeline. Only the phase in progress opens, with a progress bar and the agents working now, including those waiting for a file.
  • Tap See all N in this phase to open the run screen, which handles up to 200 agents. Tap an agent to read its brief, files, report and full output.
  • Tap Open report to read the run summary.

You can't, and why

  • Use Hive in the published app: it only exists in the build under test.Not yet
  • Run Hive on the Free plan beyond its one free run: once it is used, the Pro screen opens before the planner starts.Pro
  • Run two Hive runs at the same time: one is active in the whole app and a second waits in line.By design
  • Go past 200 agents or 20 phases in one run.By design

Cortex

Cortex is a single place to drop work: it splits each job, hands the parts to your AI sessions (each one with the live context of its own topic) and brings the results back together. It replaces the chat's whole interface (its own bar, agent strip and feed), not just one turn, and leaving it doesn't stop the agents that are working (Agents keep working).

How you get in, and what it costs

  • Tap the engine chip and then Cortex › at the end of the menu. It is the only way in: the header has no Cortex icon. The first time, a welcome sheet appears. Cortex uses one conversation of its own per project, hidden from the Conversations sheet, and leaving it takes you back to the conversation you were looking at.
  • Cortex is Pro. Without the plan you get 3 free missions: a mission is counted when it ends, and only if something got done, per account and with no clock. The offer has a remote switch, so if it is turned off Cortex is Pro only. When the missions are used up you see Cortex is part of Pro. Your free missions are used up.

Numbers to know

WhatValue
Fronts at the same time2 by default. Cortex: things at once (Settings → AI) sets 1 to 4; the engine's own ceiling is 6.
Nodes in one planUp to 8.
Jobs waiting while a mission runsUp to 3. Beyond that: Cortex is already on something. Wait for it to finish before sending more.
Waiting for your approval of an external action3 minutes. After that the agent carries on without that permission, and the request stays in the queue so you can approve it later.
Factory agents4: Code, Review, Tests and Docs, each with only the tools it needs and no fixed model (they use the one of the turn). A .md file of yours with the same name replaces one.

Welcome

The first time you enter Cortex a sheet explains it, once.

You can

  • Read Cortex hands the work out: you say what you want, Cortex splits it, gives each part to a session that knows about it and comes back with the answers grouped. You keep writing to Cortex, never to an agent by mistake.
  • Choose How much can it decide without you? (three levels, see Autonomy) and tap Start. You can change this whenever you like, from the Cortex menu.

You can't, and why

—

The Cortex screen

Cortex replaces the chat bar and the thread with its own bar, agent strip and feed.

You can

  • The top bar's title is the mission; its icons are Mission work, Agent catalogue and Leave Cortex.
  • The agent strip has a tile per session with its state (in line, working, waiting on you, broke, asleep), the cost of the mission (mission ~N tokens) and a stop button for one agent (Stop <agent>. The others keep working.). It warns when an agent is stuck (Nothing has happened here for N minutes. or It keeps going over the same step.). Tap a tile to open that agent's session; Back to Cortex returns.
  • With nothing going on, Drop work on me shows your agents and + New agent. Just type and Cortex picks the agent.
  • The control bar has the Autonomy chip, the Cortex model chip (by default The same one as the chat), Create an agent and Stop, which ends the mission and keeps what is done.
  • The feed shows the plan, the questions of the agents grouped (with the recommended answer already ticked, You decide to let Cortex pick and show you what it picked, and Continue) and, at the end, a closing card (Cortex has finished) with Keep this and Undo this for each lane, This was left waiting on you: and It also touched files it had not said it would:.
  • When an agent fails the card says <agent> could not finish and offers Try again, Give it to another and I'll do it. The last one turns Cortex off, takes you to that agent's conversation and writes what it was doing in the box, without sending it.

You can't, and why

—

The Agents catalogue

Open it with the Agent catalogue icon: Agents, with N sessions · M definitions.

You can

  • Search with Search agent or definition and read the sections Waiting on you, Under way, Asleep and Not started yet. With nothing it says No agents in this project yet. or No agent matches that.
  • Edit an agent, see never used ones, tap Save for every project to promote a project agent to every project, and + New agent.
  • Turn a conversation into an agent from the Conversations menu (Turn into an agent): it keeps its history and context.

You can't, and why

—

The agent editor

New agent or Edit agent. An agent is kept as a file, so it travels with your project.

You can

  • Start from Review, Code, Tests or Documentation, or fill the fields from blank.
  • Set Name, What it is good at (the line Cortex reads to decide whether a job is for it), Instructions, Language (optional) and Files it writes, which are glob patterns that let two agents work at the same time without stepping on each other.
  • Under What it can do choose Read only, Read and write or Everything, or tick your own tools by category (the 15 categories of the chat). Under Where it works choose the whole project or real folders of it. Pin a Model or tap Use mine.
  • Choose Where it is kept: This project (<project>/.pocketcode/agents/<name>.md, which travels with the repository) or Every project (only on this device, for your account). Then Save or Save and use it. An agent that already exists stays where it was kept; to move it use Save for every project.

You can't, and why

  • Keep an agent in This project with no project open: Open a project first, or keep it for every project.​By design
  • Reuse the name of an existing file: There is already a … here, and someone may have written it by hand. Give this one another name.​By design
  • Give an agent a tool outside the 15 categories of the chat.By design

Autonomy

Choose how much Cortex may decide without asking you, from the Autonomy chip or the welcome sheet. Whatever it decides, you see it and one tap undoes it.

LevelWhat it does
Asks often (the default)A question such as “Do I keep Material 3?” reaches you with the recommended answer already ticked.
Reversible onlyIt repeats what you already decided and shows you the card that says so.
AutonomousIt decides names, formats and order by itself. To touch the terminal, publish or write outside what it said it would touch, it still asks.

You can

  • Change the level from the Autonomy chip of the Cortex bar and tap Save.
  • Read each automatic decision as a note (I decided this: …) and tap No, ask me to undo it: Undone. It will ask you next time.

You can't, and why

  • Have Cortex decide something silently: every automatic decision is shown and can be undone, even at the most autonomous level.By design

Mission work

Open it with the Mission work icon.

You can

  • Use the tabs Artifacts, Files and Running, which cover the whole mission (tap an agent to see only its own). Open an artifact in the viewer or a file in the editor.
  • With nothing yet it says Nothing yet. Artifacts, files and anything running will show up here as your agents work.

You can't, and why

  • Create artifacts inside a mission: the artifact tool is not offered there.By design
  • Give an agent more permissions than the agent that asked for the work: permissions only narrow when work is delegated.By design

Auto-Iteration

Auto-Iteration builds a project from a description. You describe it, the AI proposes a plan (architecture, modules, tasks), you review it and it runs the tasks one by one. Open it by typing /loop in the chat: it covers the chat as a screen of its own and has no plan gate.

Command steps are posted to the terminal, and the engine counts them as done without waiting for or reading their result: creating directories, git add -A && git commit -m "[auto-iteration] <task>" after each task (with Commit Per Task on, the default) and the build, test and run-command tasks. A failed build or test does not stop the plan, so check the Terminal yourself.

The five screens

  1. 1Session list — Describe your project and Generate Plan. Previous Sessions lists old ones, with delete. The placeholder suggests “Create a calorie tracking app with meal logging, barcode scanner, and weekly reports…”.
  2. 2Planning — Analyzing your request… and “The AI is designing the architecture, modules, and tasks”.
  3. 3Plan review — The Architecture (pattern and layers), the Tech Stack, the Modules (N) with their files and the Tasks (N) with their dependencies. Then Execute Plan, Refine Plan (What should be changed?), Regenerate or Cancel.
  4. 4Execution — Progress as N/M tasks, the current task and the tokens used (with “~”: always estimated), Pause and Resume, and Cancel. A notice appears past 80 % of the time, token or iteration budget, and Stopped: the session ran out of its time budget. Raise it in settings and resume. when one runs out.
  5. 5Completed — Project Generated! with Tasks completed, Modules created, Files generated, Tokens used, Duration and Failed tasks, and Back to Sessions.

Sessions and what they keep

A task is PENDING, BLOCKED, IN_PROGRESS, VALIDATING, COMPLETED, FAILED or SKIPPED. The plan uses 10 architecture patterns and 15 task types (scaffold, create or modify a file, install dependencies, configure, UI, logic, data, tests, build, run tests, refactor, document, run a command, review).

You can

  • Pause and resume inside the same app session. Time counts only while it runs, so pausing for days spends none of the Max Duration.
  • With Validate After Each File on (the default), tasks that carry rules are validated. The syntax check only balances braces and parentheses, and the AI review reads the first 2,000 characters of the file; if the review itself fails with an error, the file counts as passed. There is no linter.

You can't, and why

  • Resume a session after you close the app: sessions live in memory for as long as the app process lives, so closing the app loses them. There are no resumable checkpoints.Not yet
  • See Backlog, Todo, Review and Done columns or specialised workers: the screen shows N/M tasks and the current task. The board and the workers belong to AI Office.By design
  • Give each agent its own reasoning level: that exists in AI Office, not here.By design

Iteration Settings

The gear of the Auto-Iteration screen opens Iteration Settings: 30 controls in 7 sections. Max Parallel Tasks and Commit Per Task only appear while Parallel Execution and Git Integration are on, so you see 28 with both off.

SectionControls
AI ProvidersPlanning Provider, Coding Provider, Review Provider (each Default (active provider) or a specific one) and Provider Rotation.
ExecutionMax Iterations (10 to 200), Max Duration (5 to 120 min), Token Budget (50K to 2000K), Pause After Each Task, Pause on Error, Auto-Retry Failed Tasks, Max Retries per Task (1 to 10), Parallel Execution and Max Parallel Tasks (2 to 8).
Code QualityValidate After Each File, AI Code Review, Quality Threshold (30 to 100 %), Generate Tests and Generate Documentation.
Project ScopeTarget Language, Target Framework (empty means Auto-detect), Code Style (Default, Minimal, Verbose, Enterprise, Startup or Academic) and Working Directory (Current project root).
Git IntegrationGit Integration and Commit Per Task.
NotificationsPlan Ready, Task Complete, On Error and Session Complete.
AdvancedUse Project Memory and Custom Instructions.

Defaults

  • 50 iterations, 30 minutes and 500K tokens. Pause on error on, pause after each task off, auto-retry on with up to 3 retries.
  • Validate after each file on. AI review on with a quality threshold of 70 %. Generate tests on, generate documentation off.
  • Git integration on and commit per task on. Notifications on for plan ready, error and session complete, off for task complete.
  • Use project memory on. Parallel execution off (2 tasks at a time if you turn it on).

You can

  • Move the sliders, switches and fields of the seven sections.
  • Choose a different provider for planning, coding and review, or let them rotate.

You can't, and why

  • Set the planning and coding temperatures or the list of rotation providers from this sheet: they exist in the configuration but have no control.Not yet

Changes, checkpoints and errors

Three things protect your files while the agent works: the file changes bar (keep or undo each file), the checkpoints (restore the project and the conversation to an earlier turn) and the turn summary.

Changes in the thread and the file changes bar

After the agent edits files you can review what it did and undo it.

You can

  • A bar above the composer shows the number of files and the lines added and removed. Open it to Keep or Undo each file, or use Keep all and Undo all. A rejected file shows Reverted.
  • Under each reply a Changes card lists the files of the turn (NEW, EDIT, DELETED) and the Commands it ran (exit N, done or failed). Tap a file to open it; Review all changes opens a sheet with the diff of every file.
  • Undo turn appears on the last turn only, when it changed files, and opens the same Restore here dialog as a checkpoint.

You can't, and why

  • Accept or reject from the Changes card in the thread: it only tells the story. The bar above the composer is where you keep or undo.By design

Checkpoints, edit and redo

Between turns that changed files, the thread shows a Checkpoint divider.

You can

  • Tap Restore here. Restore this checkpoint? says the files on disk go back to their state at that point and later messages are hidden. Then Conversation restored to checkpoint. Redo to return to latest. and Redo put everything back.
  • Edit one of your messages: Edit message? restores the conversation to that checkpoint, resends your edited message and removes the later ones (Edit & resend).
  • Checkpoints live in a shadow Git repository per conversation inside the app's private storage. It never touches your own .git, works even when the project isn't a Git repository and also captures what a CLI wrote.

You can't, and why

  • Restore files Git never saw: a restore only touches the files that differ between snapshots.By design
  • Keep the exact Redo state after you restart the app: it lives in memory.By design

Turn states, errors and interruptions

Every turn ends with a one-line state, and failures come with a card that offers the way out.

Turn states

Working · … and Thinking · …The turn is running.
Worked 12 s and DoneIt finished.
Waiting for youIt needs an approval or an answer.
Stopped by an errorA card explains the cause and what to do.
Stopped by youYou pressed stop; what was generated is kept.
Paused · context fullThe context filled up; compact and continue.

You can

  • When a turn fails, a card shows a plain title and a main action that fixes it, with Technical details and Copy folded away. The Troubleshooting section lists the real texts.
  • Automatic retries say so (We retried for you (1/3): …), and a rate limit shows Retry in Ns.
  • An interrupted turn (the process was killed) says This turn was interrupted. You can retry it or carry on from here. with Retry and Carry on.
  • A full context pauses the turn (The conversation filled this model's context. What it did is kept.) with Compact conversation and Continue.
  • Linking GitHub for Copilot shows Link your GitHub account: copy the code, tap Open GitHub and send another message once you have signed in.

You can't, and why

  • Have the chat pick another model for you when a provider retires one: it says This provider no longer offers “<model>” and lets you choose, because the model decides what a turn costs and what it can do.Third party

Free and Pro

Providers are free to connect on both plans (you bring your own key or sign-in). What the plan changes in the chat is this:

FeatureFreePro
Chat with any provider, 5 access levels, tool permissions, Effort, attachments, mentions, skills and prompts, artifacts, checkpoints, exports, voice and read aloud, context compression, Auto-IterationYesYes
Swarmcode engine2 free runs (counted when a run ends with something delivered; the offer can be switched off remotely), then choosing it opens the Pro AI sheetYes
Cortex engine3 free missions (counted when a mission ends with something done; the offer can be switched off remotely)Yes
The agent creates and edits Workflows (workflow__create, workflow__update)No: the tool is refused with a message to the modelYes
The agent lists, reads and runs Workflows (workflow__list, get, runs, run)Yes (running only the ones you marked as available to the AI)Yes
The agent rolls back a deployment or writes to your backendNo: reading status, logs and variable names is freeYes
The agent triggers a deploy (deploy_trigger)Yes, while you are under the cap of active deployments (1 on Free)No cap
Cloud Sync of your conversationsNoYes (it uploads full messages: see Privacy)
AI Office (opened from Activity or Tools)NoYes
Prices and the full comparison are on the Plans & pricing page. In the chat nothing is capped by plan: no message, conversation, token or provider limits.

Privacy and security

Your code goes to the AI provider you chose and nowhere else, unless you turn on Cloud Sync. This is what moves and where things are kept.

  • What leaves your device. Your message, what you attach, the context the app builds for the turn (the open file up to 4,000 characters, the project name, a list of paths, a map of the repository, the project memory up to 4,000 characters, your mentions and the results of tools) and the trimmed history. It goes from your device to the provider you chose, after you accepted Send to <provider>? for it. Avoid sharing secrets or personal data you don't want processed.
  • Masking. Before a prompt and the history leave, common key shapes (OpenAI, Anthropic, Google, GitHub, AWS, Slack and Stripe keys, and private-key blocks) are masked, and so are the values of your stored secrets. It is a safety net with high precision, not a guarantee.
  • Your keys. They are encrypted with a key held by the Android Keystore, per account, and travel only in the headers of the request to their provider. The AI providers page describes the key sheet.
  • No-network mode. Zero-egress (no network AI) in Settings → AI stops every network AI call. The chat then says Nothing leaves this device, and external images stay unloaded.
  • Where your work is kept. Conversations and messages in the app's local database; checkpoints in a private shadow Git repository; artifacts in <project>/.pocketcode/artifacts/; project memory in <project>/.pocketcode/memory.json.
  • Memory files in your project. Before each turn, when there is memory, PocketCode writes a delimited block into .pocketcode/MEMORY.md, CLAUDE.md, GEMINI.md and AGENTS.md at the project root and leaves your own text outside the block untouched. PocketCode writes them, but the chat doesn't load AGENTS.md, CLAUDE.md or similar files as instructions.
  • Cloud Sync (Pro). The only thing that sends conversations anywhere other than your provider. When it is on, the title, last message, provider, model and the full messages of the conversations updated in the last 180 days are uploaded to your own account in Firebase Firestore, including the tool calls, the reasoning and the file-change records of each message.
  • Content from outside. When a turn pulled in content from outside (a web page, git pull, a database query, backend logs or another agent's output), memory written in that turn is marked and is no longer fed back on its own. Project memory is shown to the model as data, not as instructions.
  • Images and artifacts. Images from other sites are not loaded without your tap, and artifacts run in a view with no network.
  • Voice. Dictation uses Android's speech recognition only while you hold the mic open; PocketCode doesn't store the recordings or send them to its servers.

Limitations

The limits that matter most, with the reason for each. The sections above list the rest next to the feature they belong to.

  • Send a PDF or any other binary file: it is accepted but not sent.Not yet
  • Search a large project with the file picker or @folder: they only see the first 50 files.By design
  • Archive a conversation.Not yet
  • Resume an Auto-Iteration session after closing the app, or rely on its command steps to report failures.Not yet
  • Read what each Swarmcode agent did inside.Not yet
  • Sign in with ChatGPT (Codex) on a device that isn't 64-bit ARM: the Codex binary ships only for arm64-v8a.Device
  • Send images with GitHub Copilot or with OpenAI signed in through ChatGPT.By design
  • See your Gemini quota, or the Codex limits of a ChatGPT Free plan: the providers don't publish them.Third party
  • Keep a turn running after you remove the app from recents.Device
  • Run bash-only commands: the agent's shell is POSIX sh (BusyBox ash) with a 30 s default and a 120 s maximum per command.Device
  • Use Swarmcode beyond 2 free runs, Cortex beyond 3 missions, or the agent's Workflow creation, rollback and backend writes on the Free plan.Pro
  • Approve an action from a notification: it only opens the conversation.By design

Troubleshooting

The titles are the messages the app shows. The buttons named in each answer are the ones on the card.

This provider isn't set up yet

There is no key or sign-in for that provider. Tap Open settings: it opens the key sheet on that provider.

Your API key was rejected

The provider answered that the key is not valid. Tap Check your key to edit it.

The provider is limiting requests

A rate limit. Tap Retry (it counts down as Retry in Ns while it waits) or Choose another model.

The provider had a problem on its side

A server error. Tap Retry. The chat also retries on its own and tells you (We retried for you (1/3): …).

Your quota with this provider ran out

Tap Use another provider or See usage to open the Context and usage sheet.

That model is no longer in this provider

The provider retired it. Tap Choose another model; the chat doesn't pick one for you.

Your account can't use this model

The account you signed in with doesn't include that model. Tap Use another provider or Use an API key.

You have cloud AI turned off

The no-network setting (Zero-egress (no network AI)) is on. Tap See the setting.

The conversation no longer fits

The context overflowed. Tap Compact conversation, or start a new conversation.

The provider went quiet

The reply stopped halfway. Tap Carry on to continue from the text already received.

The connection dropped

The connection was cut in the middle of the reply. Tap Carry on.

The model never started

The connection is alive, but the model hasn't started answering yet. The provider may have it in a queue: you can keep waiting (Carry on), or stop and pick another model (Choose another model).

Your agent stopped because everything it tried failed

Every tool call of that turn failed. Open the tool calls (Show tool calls) to see why, then send the request again.

Your agent stopped after N rounds so it wouldn't keep going in circles. Send it again to carry on.

Only the fallback path, for models that can't call tools natively, stops after 10 rounds. Send the request again to continue.

The model's context window (N tokens) is too small for the system prompt, the tools and your message.

The message goes on: “Load the model with more context, or switch to Ask or Plan mode, which offers fewer tools.” In the current app those modes are the No tools and Read only access levels.

The request was too large for the model, so it was rejected before running.

Images count for far more than their text does, which is why the estimate said it would fit. The history for the next attempt has been cut back: send it again.

File is too large (max 500 KB)

Text and code attachments over 500 KB are refused. Images have their own limit of 25 MB.

<model> cannot see images. Switch model or remove the image.

The model, or the way you are signed in (GitHub Copilot, ChatGPT through Codex), can't take images. Switch model, or tap Remove on the attachment.

Voice input isn't available for this language — change the system language or install the speech pack from settings

Android has no speech pack for the language of the device. The other voice messages (Microphone permission is required for voice input, Voice input isn't available on this device, Voice input needs an internet connection) have the cause in their own text.

Cortex is already on something. Wait for it to finish before sending more.

Up to 3 jobs wait in line while a mission runs. Beyond that, wait for the mission to end.

There is no agent to hand this to yet. Turn a conversation into an agent from its menu.

Cortex has no agent in this project. Use Turn into an agent in the Conversations menu, or + New agent.

Cortex is working without background protection: the system may stop it. Open the app again to keep it going.

The system refused to start the foreground service. Activity shows the same state as Not protected in background. Bring the app to the front to keep the work going.

The preview stopped working.

The artifact view crashed. Tap Reload preview.

Stopped: the session ran out of its time budget. Raise it in settings and resume.

Auto-Iteration hit its Max Duration (it can be the token or the iteration budget too). Raise it in Iteration Settings and tap Resume.

Dev Browser is not open. Ask the user to open the Dev Browser, then call this tool again.

The agent's browser_* tools need the Dev Browser to be open. Open it from the editor and ask again.