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.

Ways to open it
| Where you are | What you do | What happens |
|---|---|---|
| The main pager | Swipe to the fifth page. The indicator shows five dots and the last one is lit. | The AI Chat page. |
| The command palette | Run the AI Chat command. | The AI Chat page. |
| Home | Tap the AI Assistant quick action in Quick actions. | The AI Chat page. |
| The code editor | Select 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 notification | Tap 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 link | Open 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/chatcarries 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.
| Screen | How you get there | What you can do |
|---|---|---|
| AI Chat page | Fifth 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. |
| Header | Top of the page. | Change the model, open Conversations, the ● N activity chip and the Conversation menu (⋮). |
| Empty state | A new conversation. | Start from ten shortcuts, or fix what blocks you: no provider, no network, the no-network setting. |
| Thread | The 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. |
| Composer | Bottom of the page. | Type, attach, mention with @, run / commands, dictate, send, stop or queue a message. |
| Controls bar | Right above the composer. | Access level chip, engine chip, Effort chip, the context radial and the active skill badge. |
| Model selector | Tap the model name in the header. | Choose provider and model. It is described on the AI providers page. |
| Decision, approval, secret and question cards | Above 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 bar | Above the composer, after the agent edited files. | Keep or Undo each file, or Keep all / Undo all. |
| Conversations | Header 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 tasks | Activity → open a terminal process. | Stop commands the AI left running and clear the finished ones. |
| Context and usage | Tap 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 room | Engine chip → Swarmcode; then See the agents. | Follow the phases of a run and change the model of the agents that haven't started. |
| Cortex screens | Engine chip → Cortex. | Welcome, the Cortex screen with the agent strip, the Agents catalogue, the agent editor, Autonomy and Mission work. |
| Auto-Iteration and Iteration Settings | Type /loop; the gear opens the settings. | Describe a project, review the plan, run it task by task, and tune 30 settings. |
| Pro walls | Once 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
/loopcommand.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
| Shortcut | Access level it sets | Skill it turns on |
|---|---|---|
| Explain code | Read only | none |
| Find bugs | Read only | /debug |
| Suggestions | Read only | /review |
| Optimize | Read only | /refactor |
| Document | Auto-edit | none |
| Write tests | Auto-edit | /test |
| Learn | No tools | /learn |
| SQL query | Read only | /sql |
| Git help | Read only | /git |
| Ask | No tools | none |
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
mermaiddraws a diagram,math,latexortexan equation andcharta chart; when a Mermaid type or a chart can't be drawn, the block stays as code.htmlandsvgblocks show a live preview once the reply has finished, with an Open in canvas button;xmlblocks 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.
| Command | What it adds to the message |
|---|---|
@file Current file | The content of the open file, cut to its first 4,000 characters. |
@project Project tree | A list of file paths, up to 100 in the message (the list itself comes from the 50-file scan described below). |
@problems Problems | The current errors and warnings from the diagnostics. If there are none, the message says no diagnostics are available. |
@terminal Terminal | The last terminal output. |
@codebase Codebase | A semantic search of your project: the 5 best matches, 800 characters each. |
@web <url> Web | The text of the page. Up to 3 addresses per message. |
@diff Git diff | Your uncommitted changes: up to 30 files, 20,000 characters in all and 6,000 per file. |
@folder <path> Folder | The 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
@folderonly 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__,.ideaand.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
@codebasewhen 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.
| Command | What it does |
|---|---|
/help | List every available command. Shows them grouped as General, Conversation, Memory, Skills, Context and Custom prompts. |
/new | Start a new conversation. |
/loop | Open autonomous auto-iteration. Opens Auto-Iteration. |
/remember key = value | Store a project memory. Saves a note the agent reads in every turn of this project. |
/forget key | Remove a stored memory. |
/memory | Show stored project memories. |
/skills | List available skills. |
/skill-off | Deactivate the active skill. |
/compact | Compress 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.
| Command | Skill (as the app names it) |
|---|---|
/debug | Debug: expert debugger, focused on finding and fixing bugs. |
/refactor | Refactor: code refactoring specialist, cleaner and more maintainable code. |
/sql | SQL Expert: database and SQL specialist. |
/git | Git: version control expert. |
/deploy | Deploy: deployment and DevOps specialist. |
/learn | Learn: teaching mode, explains concepts step by step. |
/review | Code Review: finds issues and suggests improvements. |
/test | Testing: writes and improves tests. |
Your own agents, modes and prompts
- Every
.mdfile 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 setname,description,icon,command,model,provider,tools,skills,languageandscope; the body of the file is the system prompt. Cortex's agent editor writes these files for you. - Every
.mdfile in.pocketcode/prompts/(and the ones installed from the Marketplace) is a command/<file name>. Its front matter can set adescription, 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 later | Off (not on Pro models), Low, Medium (the default), High and Max. |
| GitHub Copilot | Whatever 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 endpoint | No 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.
The five access levels
| Level | What the app says | What the agent does |
|---|---|---|
| No tools | Text only, doesn't read files | It gets no tools: every call is refused. |
| Read only | Reads and searches, changes nothing | Reads and searches. Anything that writes, runs or changes something is refused, not asked. The catalogue drops to 56 tools. |
| Ask first | Asks before writing or running | Reads freely. Writing a file, running a command, deploying or any other change waits for your OK. |
| Auto-edit | Writes alone, asks before running | Also writes files on its own (a snapshot per file is kept, so you can undo). Commands and deploys still wait for your OK. |
| Full access | Asks only to go off-device or to memory | Everything 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
| Choice | What the app says | What it does and what it costs |
|---|---|---|
| Chat | One agent, step by step with you | Free. One model, its tools and this thread. |
| Swarmcode | Several agents try, judges pick the best | Pro, 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. |
| Cortex | Named agents on several fronts | Pro, 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-iteration | Free. 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
| Category | Tools 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_terminalruns in POSIXsh(the BusyBoxashthe 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_filerefuses 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_dirgoes 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_executeand 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_memorystore 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_cookieandsecretschange 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
| Type | What the viewer shows |
|---|---|
html | A live page in a hardened view. |
svg | The 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. |
code | Source 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
artifacttool 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
.extfile, 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.htmlare 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
.gitor.pocketcode, or outside the project, with In the open project: the dialog refuses the path.By design
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
| Format | What 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 three | Stored 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.
/compactdoes 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
- 1Plan: the lead decides how many agents are needed (Deciding how many agents are needed), from 1 up to the attempts of your Intensity.
- 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.
- 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.
- 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: Quick | 2 attempts, 1 judge, up to 1 review round |
| Intensity: Balanced | 3 attempts, 3 judges, up to 2 review rounds. The default |
| Intensity: Thorough | 5 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 provider | Off |
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.
| Adversarial | Hive | |
|---|---|---|
| Good for | One question, the best answer | A big task, done end to end |
| How it works | A few drafts of the same thing, and judges that try to knock them down | A planner splits the task into phases and agents made to measure, an engine runs them, and the planner wraps up |
| How many agents | Up to 2, 3 or 5, depending on the Intensity (Quick, Balanced or Thorough) in Swarmcode settings | As many as the task needs, up to 200 per run |
| Who writes files | Only the Build mission: one applier agent, after the judges | Each agent that has write access, without stepping on each other |
| Look | Teal, with the usual Swarmcode icon | Orange, with a honeycomb icon |
How a Hive run goes
- 1Tap the engine chip, choose Swarmcode, then Hive under Flavor. The mission row only shows with Adversarial.
- 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.
- 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.
- 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.
- 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. - 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
| What | Value |
|---|---|
| Fronts at the same time | 2 by default. Cortex: things at once (Settings → AI) sets 1 to 4; the engine's own ceiling is 6. |
| Nodes in one plan | Up to 8. |
| Jobs waiting while a mission runs | Up to 3. Beyond that: Cortex is already on something. Wait for it to finish before sending more. |
| Waiting for your approval of an external action | 3 minutes. After that the agent carries on without that permission, and the request stays in the queue so you can approve it later. |
| Factory agents | 4: 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.
| Level | What it does |
|---|---|
| Asks often (the default) | A question such as “Do I keep Material 3?” reaches you with the recommended answer already ticked. |
| Reversible only | It repeats what you already decided and shows you the card that says so. |
| Autonomous | It 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
artifacttool 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.
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
- 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…”.
- 2Planning — Analyzing your request… and “The AI is designing the architecture, modules, and tasks”.
- 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.
- 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.
- 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.
| Section | Controls |
|---|---|
| AI Providers | Planning Provider, Coding Provider, Review Provider (each Default (active provider) or a specific one) and Provider Rotation. |
| Execution | Max 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 Quality | Validate After Each File, AI Code Review, Quality Threshold (30 to 100 %), Generate Tests and Generate Documentation. |
| Project Scope | Target Language, Target Framework (empty means Auto-detect), Code Style (Default, Minimal, Verbose, Enterprise, Startup or Academic) and Working Directory (Current project root). |
| Git Integration | Git Integration and Commit Per Task. |
| Notifications | Plan Ready, Task Complete, On Error and Session Complete. |
| Advanced | Use 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 Done | It finished. |
| Waiting for you | It needs an approval or an answer. |
| Stopped by an error | A card explains the cause and what to do. |
| Stopped by you | You pressed stop; what was generated is kept. |
| Paused · context full | The 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:
| Feature | Free | Pro |
|---|---|---|
| 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-Iteration | Yes | Yes |
| Swarmcode engine | 2 free runs (counted when a run ends with something delivered; the offer can be switched off remotely), then choosing it opens the Pro AI sheet | Yes |
| Cortex engine | 3 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 model | Yes |
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 backend | No: reading status, logs and variable names is free | Yes |
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 conversations | No | Yes (it uploads full messages: see Privacy) |
| AI Office (opened from Activity or Tools) | No | Yes |
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.mdandAGENTS.mdat the project root and leaves your own text outside the block untouched. PocketCode writes them, but the chat doesn't loadAGENTS.md,CLAUDE.mdor 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(BusyBoxash) 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.
Next