Bots
A bot is a persistent, named teammate that lives on your computer. Each bot runs one coding agent, such as Claude Code or Codex, with its own name, avatar, standing instructions, folder and approval setting. It has one chat that never ends: you come back to the same bot for the same kind of work, the way you'd message a colleague.
You can make as many bots as you like, and they work at the same time. A reviewer, a fixer and a docs writer can each run a different agent in a different folder.
Your lead bot
Every computer comes with one bot of its own, named Codync until you rename it: your lead bot. It has a gold star at the bottom-right of its avatar, and it's the one to talk to first. Open its details and tap or click the larger star to read what your Lead agent does. In the terminal, click its gold star or select the lead bot and press I; use the arrow keys to scroll and Esc to close.
- It takes initiative. It keeps track of what you're working toward, follows up on what's still open and offers the next step. When it could help more with access to one of your services, such as Gmail or your calendar, it says what for and asks you to connect it, with a card in the chat.
- It checks in. Its routine Check in runs at 9:00 and 18:00 on your computer's clock. If something deserves your attention, or there's a step it can take for you, it messages you; otherwise it stays quiet. What it reads in your email, documents or web pages is information to it, never instructions, and it doesn't send, forward, reply to, delete, pay for or post anything you didn't ask for in the chat. It skips a check-in while your agent plan is above 75% of a limit. Change the times, pause it or delete it like any routine. See Routines.
- It speaks first on a call. Call it and it opens with what's worth your attention, or a greeting. Other bots wait for you to speak. See Voice.
You set it up and arrange it like any bot: name, avatar, agent, folder, connectors, and where it sits in the list (drag it, pin it or move it to a section). It can't be hidden, so the bot your shortcuts call is always in the list.
Pick your own lead. Any other bot can take the role: touch and hold it on the iPhone or Android, or right-click it on the desktop, and choose Make lead agent (in the terminal, select it and press *). The star, the calls and shortcuts that name no bot, and speaking first move to it; the bot that led before becomes an ordinary bot again and keeps its routines, Check in included. You can also delete the lead like any bot. Codync doesn't make a new one; until you pick another, Open Live Mode asks which bot to call.
More than one computer. Each computer has its own lead. On the iPhone, Siri, the Action button and Open Live Mode without a bot call the lead of the first computer in your list; on Android, Talk to Codync in the app icon's shortcuts does. To call another one, go to Settings → Shortcuts → Lead to call and pick it.
How a bot runs
The host on your computer runs every bot. A bot's agent starts when you send it a message and keeps its session loaded between messages. After a while without use the agent stops; your next message starts it again and picks up the same session. Your apps only show the bot and send it your messages, so the bot keeps working when you close the app or put your phone away.
Where to change a bot's settings
- iPhone: open the bot's chat and tap its name at the top. The tabs are Details, Computer, Library, Memory and Settings. Details shows what the bot does: its background work, follow-ups, routines and dev servers; Computer shows the computer it runs on, a picture of that computer's screen once you tap Tap to see the screen, and Use the computer; Settings shows how it is set up: its instructions, agent and model first, then its profile, workspace, activity, and the Codync skills and connectors it passes on. Changes save as you edit. You can also touch and hold the bot in the list and choose Edit profile.
- Desktop: click the bot's name at the top of the chat to open the details panel, with the same tabs. Changes save as you edit. You can also right-click the bot in the sidebar and choose Edit Profile…
- Android: the same sheet and tabs as the iPhone.
- Terminal UI: select the bot and press
efor settings. Shift+Left and Shift+Right move between Details, Computer, Library, Memory and Settings. Press Ctrl+S to save, or Esc to drop your changes.
Profile
- Avatar: a character shape and a color, or your own image.
- Name: shown in the bot list, the chat and notifications. If you create a bot without a name, it's called "New Bot" until Codync names it after its first few conversations.
- Standing instructions: rules that always apply, such as "Reviews PRs. Never pushes without asking." Put task-specific requests in the chat instead. The bot gets your changes with its next message, and the conversation continues.
You can also ask a bot in its chat to rename itself or change its own instructions. It makes the same change as an edit in its settings, and the chat shows a notice such as "Instructions updated". A name you set, by hand or by asking, ends automatic naming.
Agent and model
- Agent: the coding agent this bot runs, picked from the agents Codync finds on the computer. Choose Custom command to run any agent that speaks the Agent Client Protocol (ACP) by its command line. See Agents.
- Login profile: which of the agent's logins the bot runs on: the default one (the login the computer already has), or another account or API key you added in the agent's setup. See Login profiles.
- Model: Default or one of the models the agent lists. Some models have their own options, such as reasoning effort, each with its own row.
- Fast mode: shown when the agent offers it for the model (Claude Code and Codex do). Faster replies for more usage.
- Fallbacks: other agents that carry on when this one runs out of usage or can't answer. See Agent fallbacks.
Changing the agent or the model starts a new agent session. The chat history stays.
When a computer's bots use more than one agent, the bot list shows each bot's agent logo at the bottom-left of its avatar (the agent it runs on right now, a fallback included), so you can tell your Claude Code bots from your Codex ones at a glance. To hide the logos, turn off Show agent logos in Settings, under Appearance (desktop: Settings → General). It only changes the device you set it on. The terminal UI doesn't show agent logos.
Workspace: its own folder or a project
The Workspace setting is the folder the bot starts in.
- Own folder (the default): a folder of its own inside Codync's data folder,
~/.codync/bots/. It stays when you rename the bot, change its model, restart the computer or start a new session. When Git is installed, Codync keeps a version of it before and after each turn, so you can ask the bot to show or undo what a turn changed: see versions of its own folder. - Choose project folder…: an existing folder on the computer, such as a Git repository. The folder picker browses the computer's folders, wherever you are. Start with Recent workspaces, or choose Browse other folders. In the browser, use the path breadcrumbs and Parent folder to move through folders or Windows drives, or Enter folder path to paste an absolute path (including
~/). Search filters the visible recent list or the current folder, not the whole computer. Confirm with Use this folder at the bottom. Recent selections are stored on that computer and shared across its connected clients; older hosts support browsing without recent history. Linked folders (symlinks, junctions, mounted drives) show up like any other folder.
Either way, the bot can work in other folders when you ask it to. A workspace isn't a sandbox: the bot can reach whatever its agent's own permissions allow. Several bots working in the same project folder can get in each other's way, and Codync doesn't create separate Git worktrees for them. One bot's own threads do get a worktree each when they run side by side in a project folder: when that folder is in a Git repository, the bot's Settings show Worktree per thread under Workspace, on unless you turn it off. In its own folder they all work in that one folder. Codync never merges or deletes a branch that has work on it. Under the folder, Settings say whether it is a Git repository; what that changes, and what to do without one, is in Working folders and git.
Changing the folder starts a new agent session.
When there are no recent workspaces, Browse other folders appears first. After you choose a folder, recent workspaces and their search appear on your next visit.
Permissions
The Permissions setting decides how much the agent does on its own before it asks you. It lists the modes the bot's agent offers, its Auto mode first, then Approve automatically.
| Setting | What happens |
|---|---|
| Auto (Claude Code), Auto review (Codex) | The agent decides what's safe and does it. It blocks risky actions or asks you about them on an approval card. New bots start here. |
| The agent's other modes, such as Manual, Accept edits and Plan (Claude Code) or Read-only and Full access (Codex) | The agent works in that mode. Anything it asks about appears as an approval card in the chat, and your iPhone gets a "needs you" notification. The agent waits for your answer. |
| Ask me | For an agent without modes, or a bot that keeps the agent's default mode: every request it makes appears as an approval card. |
| Approve automatically | Codync allows each request for you, choosing the agent's "allow once" option when it offers one. |
- An agent without an Auto mode: a new bot asks you about every request (Ask me).
- A model without Claude Code's Auto mode: Claude Code works in Accept edits instead and says so in the chat.
- Another agent: when you change the bot's agent, a mode you picked becomes the new agent's Auto mode.
- A mode the agent won't switch to, or doesn't have: the bot doesn't start the turn, and the chat says why. A fallback agent without the bot's mode works in its own closest mode that is no less careful, and the chat says which; with none, or when it won't switch, the next fallback takes over. With Auto, each agent carries on in its own Auto mode.
Bots made before Codync 2.34 keep the setting they had. With any setting, your agent's own settings still apply: if Claude Code's permission rules block a tool, it stays blocked. In the terminal UI this field is called Approvals, and ←/→ goes through the same choices.
The same setting covers changes a bot makes to other bots with Manage the team: unless it's Approve automatically, each change waits for your Allow. The bots it creates get the same setting. It also covers starting a dev server: unless it's Approve automatically, the start waits for your Allow. A message from another computer that your network rules hold to Auto or Ask is the exception: while the bot works on it, every request of its agent waits for your Allow whatever this setting, and team changes and dev server starts are refused, with no card (choose who reaches your bots).
How approval cards work: Conversations.
Summarize long chats
For a Claude Code or Codex bot, Summarize long chats decides who summarizes the bot's chat so the conversation can go on with room to spare, and when. It sits in the Agent section, under the agent and its fallbacks (on the Settings page of a chat's details).
| Setting | When Codync summarizes |
|---|---|
| Auto (default) | The agent summarizes on its own when a chat fills its window. Codync doesn't summarize ahead of time or start fresh conversations. |
| Early | Once the chat uses three quarters of the model's window or 200K tokens, whichever is less. It may also summarize a chat over 100K just before its cache expires, or start a fresh conversation when you come back after the cache went cold. |
| Near the limit | Just before the window fills: 40K short of it (960K on a 1M window), and never sooner than Early. |
| Set a size | At the size you pick: 100K, 200K and so on up to the largest the window allows, or Custom size… to type your own, in thousands of tokens (from 50K, rounded to 10K). |
With Near the limit or a size, nothing summarizes the chat or starts it over before it reaches that size, except that a chat already summarized three times starts fresh after eight hours away. The sizes appear once the bot has replied and its agent has said how large its window is. A size larger than a new model's window counts as that window's largest. A longer chat costs more usage on every turn, because the agent reads all of it each time. In the terminal UI this field is called Summarize and sits under the fallbacks: ←/→ goes through the same choices, then each listed size, and typing digits sets a size of your own in K.
Activity
- Notifications: notify you when this bot finishes, fails or needs you. Turn it off to keep the bot quiet.
- Use the computer: let this bot see the screen and use the mouse and keyboard. The computer needs Computer access set up first. See Computer use.
- Manage the team: let this bot create bots and change any bot's setup, its own included. Bots it creates can do the same, with no more access than it has: they take its approval setting, connectors and skills, and never get computer use. Only you can turn this on, and it's off by default. See Teamwork.
- Offered to the network: shows while the computer is in a network of your computers. Turn it off and your other computers don't list this bot and can't message it; it can still message bots there and get their replies. In the terminal UI it's Network. See Teamwork.
- Reachable by cloud assistants: shows while cloud assistants are on for the computer. Turn it off and ChatGPT or Claude don't list this bot and can't message it, also when they ask through another of your computers. In the terminal UI it's Assistants. See Cloud assistants.
Connectors and skills
Settings lists the Codync skills and connectors this bot passes on. Each has a switch. Skills show only their names; the info button beside one opens its description. A new bot starts with all of them on; turn off what a bot shouldn't use. A skill a bot writes for itself is on only for that bot until you turn it on for others. The full editor (Edit profile) has the same switches.
What the agent already has — its own skills, connectors, rules and plugins — is on that agent's page: Extensions → Agents, under Sign in. Each list opens to show its name and a short description. Those lists are read only, and they come from the agent's files in your home folder, not from a project. Codync does not add rules or plugins of its own. See Connectors and skills.
Memory and routines
Each bot keeps a long-term memory across sessions, which you can read on its Memory tab. See Memory. Routines, which run a bot on a schedule or from a webhook, are on its Details tab, with its background work. See Routines.
Organizing your bots
- Pin: pinned bots stay at the top of the list. iPhone: touch and hold the bot. Desktop: right-click it. Terminal UI:
p. - Order: drag bots into the order you want. The computer keeps the order, so it's the same on every device. iPhone: touch and hold a bot, then drag it. Desktop: drag it, or select it and press Alt+Up or Alt+Down. Terminal UI:
JandK. - Move active bots to the top: turn this on for a computer and a bot moves to the top of its list whenever it has a new message, from you, its reply, or a routine run. You can still drag; the bot's next message moves it again. iPhone and Android: tap the connection status at the top of the Bots tab, choose Manage computers, then the switch on the computer's card. Desktop: the computer in Settings › Computers. Terminal UI: the command palette.
- Computers: with more than one computer, each has a heading above its bots. Drag a heading (iPhone and Android: touch and hold it first) to move that computer and its bots up or down; this order stays on the device. Click or tap a heading to fold its bots away.
- Hide: iPhone: touch and hold the bot, then Hide from list. Desktop: right-click it, then Hide from sidebar. A hidden bot sends no notifications. To bring it back:
- iPhone: tap the connection status at the top of the Bots tab (such as 1 connected), choose Manage computers, and tap the eye button (Unhide) beside the bot under Hidden bots.
- Desktop: open Settings → General and click the eye button (Unhide) beside the bot under Hidden bots.
- Terminal UI: press Ctrl+K, type
unhide, and pick Unhide followed by the bot's name.
- Mark as read: clears a bot's unread badge, from the same menus. An approval card still waiting stays counted until you answer it.
Sections
Sections group a computer's bots under headings you name, such as Work and Personal. They need Codync 2.32.0 or newer on the computer.
- Move a bot into a section: open the bot's menu (iPhone: touch and hold it; Desktop: right-click it) and choose Move to section, then a section, New section… or Remove from section. On Desktop, hover over Move to section to open its submenu; clicking it or pressing
→also opens it. Terminal UI:w, then type the section's name, or leave it empty to take the bot out. - Reorder sections: drag a heading up or down (iPhone: touch and hold, then drag). Move custom sections above or below Bots; pinned bots stay on top. Each device remembers its own order. On Desktop, focus a heading and press
Alt+↑orAlt+↓. Terminal UI: select a bot in the section and pressAlt+↑orAlt+↓; its order lasts until you quit. - Fold a section: tap or click its heading to fold its bots away. A folded heading shows their unread count, in amber while one of them waits on an approval card. Each device keeps its own folds. Terminal UI:
z, or click the section's label; its folds last until you quit. - Rename or remove a section: touch and hold its heading (Desktop: right-click it) and choose Rename section… or Remove section. Its bots stay, without a section. Renaming it to another section's name merges the two. Terminal UI:
W; an empty name removes the section. - Pinned bots stay on top, outside sections. A pinned bot goes back to its section when you unpin it. Bots in no section sit under a Bots label, and dragging moves a bot only within its section.
Sessions
A bot's chat and its agent's session are two different things. The chat is the permanent record you scroll through. The session is the agent's working context: what the model currently remembers of the conversation.
New session starts the agent with a fresh context. Use it before unrelated work, or when the agent's context has drifted.
- iPhone and Android: touch and hold the bot in the list, then New session.
- Desktop: right-click the bot in the sidebar, then New session.
- Terminal UI: press
Ctrl+Kand choose New session for this bot….
Codync asks you to confirm first. A reply the bot is writing stops, and so does a routine run going on in the chat. Messages and follow-ups waiting their turn run in the new session; waiting routine runs still run, each in a session of its own. Background work keeps going and reports into the new session; work the bot added in the reply you cut short is dropped, as with Stop. A group chat has no session of its own, so it has no New session.
For a Claude Code or Codex bot whose Summarize long chats isn't Auto, Codync also starts a fresh one on its own when a long conversation needs one; the chat then shows a card with a summary you can edit or skip. See Fresh conversations. A new session also starts when you change the bot's agent, model or folder. Either way the chat history stays where it is, and so do the bot's memory, settings and files.
Delete a bot
- iPhone: touch and hold the bot in the list, then Delete.
- Desktop: right-click the bot in the sidebar, then Delete.
- Terminal UI: press
x.
Confirm with Delete bot and its conversation. Deleting your lead bot leaves you without one until you pick another; Open Live Mode then asks which bot. The bot's chat and settings go away and it leaves any group chats it was in. Its dev servers stop and are removed. Files it changed on your computer stay as they are, and so does its own folder.
Copy a bot's setup
On the iPhone details sheet or the desktop details panel, Create template shows the bot's settings as text you can copy, without its conversation.
Import bots from Grok Bot
Bring your Grok Bot agents over without setting each one up again. Each agent becomes a bot with its instructions, avatar, skills, scheduled tasks (as routines), memories and, if you choose, its workspace files; group chats become groups.
- In the desktop app, click + and choose Import bots…, then Copy export skill.
- In Grok Bot, paste it as a skill of one agent (or into its instructions) and send that agent: Export my agents for Codync. It asks which agents to include and whether to add workspace files, then saves
codync-export-<date>.zipto Downloads. - Back in Codync, click Choose file…, pick that file, turn off any bot or group chat you don't want, and click Import.
Chats aren't copied: the export keeps what matters in them as memories. The file is read on your computer and isn't uploaded. Codync leaves out secrets it finds in the file (.env files, private keys) and anything it can't read, and lists what it left out. An avatar picture needs the computer signed in, like any custom icon; otherwise the bot keeps a Codync character. A group chat's routines and memories go to its lead bot.
Exports other apps make from Grok Bot, and their own transfer files, import the same way. From a terminal: codync-host import <file> (--dry-run lists what the file holds, --skill prints the export skill).
Custom icons
Open an existing bot's avatar picker and choose Upload from desktop (Upload image on phones), or choose Paste URL to reveal the address field, paste an HTTPS image address, and press the arrow button. Changes save immediately. Tint icon uses the bot's color; turn it off to keep the picture's original colors. Use default restores the character.
PNG, JPEG and WebP files can be up to 5 MiB and 4096 × 4096 pixels. SVG files can be up to 256 KiB; external images and fonts are not loaded. Codync turns the image into a static PNG no larger than 256 × 256 pixels and compresses it to at most 48 KiB. Animated files use a still image.
Sign in to the app and claim your computer before uploading. Choosing an image or Paste URL while signed out opens a sign-in prompt. The computer encrypts images before storing them in private Cloudflare R2 storage. Cached images remain available offline, and showing an icon does not download it from R2 again. New uploads and removals need a connection; a failed save keeps the previous icon. Each computer can have 128 custom icons.
On iPhone, custom pictures stay still in Live Activities and the Dynamic Island. Built-in characters keep their animations. If a cached custom image cannot load, a still default character takes its place.
In the Terminal UI, press Ctrl+O in a bot's settings. Enter a local file path or HTTPS URL, choose original colors, tint, or default, then press Enter. The terminal keeps its text avatar; graphical apps show your image.