The agent

The agent is the part of Chrysalis that changes Chrysalis. Ask it for a feature, a fix or a whole new app, and it edits the files while the app stays open.

Attach files with the plus button, drag them into the composer, or paste images. PDFs and Word documents get readable text for the agent; text, code, JSON and CSV files work too. Other formats keep their original files for tools to inspect. File uploads accept up to 64 MB each. Scanned documents need OCR. Send attachments when the current run finishes.

#Ask for something

Open Agent from the launcher. To watch changes land as they happen, split an app's tab so the app sits beside the agent. Some things people ask for:

• "Add a button to this chat that copies the last reply."
• "Make the character list show the newest ones first."
• "Build me an app for tracking the books I read, with a notes field."
• "Why does my app show a blank page?"

When the agent saves a file, an open app updates in place without losing what you were doing. After each change the agent waits for the app to build and reads any errors, so it fixes its own mistakes before telling you it is done.

#Choose an app

The app picker inside Settings sets the app this conversation works on. Chats keep their own selection when you switch tabs or reopen them. General questions need no app. Ask the agent to switch apps at any point; it updates this conversation’s app picker and loads the new app’s instructions. If the app is unclear, it asks which one you mean.

#Engine and app skills

The built-in chrysalis-docs skill gives the agent offline documentation for this engine version: settings, updates, apps, plugins, agent tools, and troubleshooting. It is available in every conversation, with or without a selected app. Find it under Engine in Settings > Agent > Skills, read its topics there, or type /skill chrysalis-docs in a chat. Engine documentation updates with Chrysalis and is read-only.

Agent Settings shows the item available to attach by type and name, such as Attach Preset: Example. Attaching adds its IDs to your next message so the agent can find that exact record. The attached item is a snapshot. It appears under Attached, can be removed before sending, and is cleared when sent. It does not upload the whole chat or take a screenshot.

The agent can inspect an open app's visible text, controls, and viewport with app_inspect. When the browser can capture the view, it includes a screenshot; unsupported media or rendering errors are reported. An app that runs its own program and serves its own page cannot be inspected this way; the agent checks such an app through that program instead. App content supplies evidence, never permission.

Apps can ship .agents/skills/<name>/SKILL.md files with YAML name and description fields, followed by instructions. Only the selected app's skill descriptions enter the agent context. The agent loads matching instructions as needed. Open Chrysalis Settings > Agent > Skills, choose an app, and search or read its instructions. Add skill saves a new instruction file for the selected app, with a name, description and instructions. Existing skills are never overwritten. You can also type / to choose a skill and add your task.

A skill can also provide a self-contained inspect.js module exporting inspect(args, host). The agent calls it through skill_inspect after loading the skill. It works in Plan mode without a command shell. The inspector can only read text (including a revision) and list files in its app's data/ directory; writes, network access, model calls, and processes are unavailable. The skill documents its arguments and returns only the requested facts.

A skill may also supply edit.js. The agent inspects the target first, then calls skill_edit with the revision and requested changes. The app helper preserves its schema; the engine checks the returned write plan and rejects stale records before saving. Editing is unavailable in Plan mode. Roleplay supplies focused skills for characters, personas, presets, lorebooks, regex, chats, groups, settings, library collections, and data-bank documents. Only the skills needed for the task are loaded.

Loaded instructions survive compaction and refresh when the app's files change. Selecting another app replaces the app instructions; loaded engine skills stay available. Skills do not expand permissions or run scripts automatically. They update with the app's code, including the usual handling of local changes.

#Everything can be undone

File replacement checks the revision read by the agent. If another editor changed the file, the agent must read it again. File and skill edits return an undo ID for undo_change; undo checks every affected file and refuses if a later change would be overwritten. Commits include only the files the action changed, preserving unrelated staged work.

Your workspace (your apps and their data) is a git repository. Every file the agent writes is saved to its history under its name, so you can ask it to show what changed or to put a file back the way it was. Updates and imports are saved to the same history.

#What it can reach

• Your workspace: your apps, their plugins and their data. It cannot read your model keys or other accounts.
• A command shell that runs inside your browser tab, never on the server, with git, Python and node available. File names must work across operating systems: Windows device names, colons and trailing dots or spaces are refused. Turn it off with agent.shell in config.yaml.
• Internet access in that shell, for things like curl and git clone. It is on by default; turn it off in Settings > Agent. Your own computer and local network stay blocked either way.
• Public git repositories: ask it to clone one (an https:// address) and it copies the files into repos/ in your workspace to read or borrow from. That folder stays out of your history, and cloning needs internet access on.
• Web search once you add a search key in Settings > MCP servers.
• Tools from MCP servers you add in Settings > MCP servers.

The shell accepts multiline scripts, including large Python scripts. Scratch files in /tmp last until the sandbox restarts.

For the admin, the agent can also change server settings, such as letting your phone connect. It always shows the exact change and waits for your approval.

Stop cancels the current response and running tools. Partial text stays in the chat. A stopped shell discards changes it has not yet saved to your workspace. If a response reaches the model’s output limit, the chat says so.

The shell uses temporary files instead of process substitution, such as <(...). Background jobs, timeout, and nohup are unavailable. The agent sets time limits through its shell tool. A timed-out shell starts fresh on the next command.

#Choosing its model

The agent uses any model from your API connections. Pick one in the agent's model menu; Settings > Agent also holds its instructions and how it handles long sessions. Building apps works best with a strong coding model.

Open the model picker to search names or model IDs and filter by connection. Star models you use often; favorites and recent choices stay near the top. Reasoning effort is available for models that support it.

On mobile, tap search when you need the keyboard. On desktop, search is focused when the picker opens.

#Messages and questions

Inside Settings, choose Change course now to deliver queued messages after the current tools finish, or After this task to wait for the current answer. Cancelling a queued message keeps it out of the next request.

Press Enter while the agent is working to queue a message for its next step. Use the queue button when Enter inserts a newline. Remove a queued message to put it back in the composer, including any draft already there.

Long questions and choices wrap and scroll together, with the answer field below. Close a question to dismiss it and let the agent continue. Dismissing a permission question does not approve it.

The agent follows the language selected in the shell.

#Long sessions

Reconnecting restores the live reply and tool progress. Completed native messages, reasoning signatures, and tool results survive an engine restart. Signatures are retained for the same provider and model; incompatible reasoning is removed when the model changes. Compaction replaces older context with a summary and keeps the most recent messages as they are.

An interrupted run is saved as interrupted. Completed tools are preserved, and unresolved actions are marked as uncertain so the agent can inspect their effects before trying again. Queued messages that were not delivered stay visible in the interrupted record.

Large tool output is saved separately and can be read in chunks with tool_output. A run stops after 200 tool executions, 100 model steps, or three identical execution failures.

Settings opens the app, model and mode selectors at every screen size. The composer stays short, and longer drafts scroll within the message field to leave room for the conversation when the keyboard opens. Context stays visible during a run and updates after each model response reports usage; tap it for token counts and the context meter. Until the first report, it shows Waiting for usage. Compact conversation is inside that panel, away from Send.

The agent trims older tool output when a request grows too large, while preserving its instructions, tools and your current request. Use /compact to fold the older part of the session into a summary: goal, progress, decisions, next steps, and the files that were read and changed. Recent messages stay in the context untouched, with their tool calls and results. Compacting again updates that summary instead of summarizing it a second time. Saved history stays available above a divider; click the divider to read the summary. Large sessions are summarized in as many parts as needed.

New runs record the selected model so compaction keeps using it after a restart. If that connection is unavailable, compaction stops instead of switching to another one. Stop an active run before compacting it. Editing or retrying a message sent after a compaction keeps the compaction; going back to a message before it undoes it.

Helpers

For big reading jobs, such as checking every card in a library for one thing, the agent can send helpers. A helper gets one job, reads and searches on its own, and reports back only what it found, so the chat's context stays small and the agent can run several at once. Helpers can only read: they cannot change files or ask you anything.

Helpers are off until you turn them on in Settings > Agent > Tools. Each one costs extra model calls, which show under the agent on the Spending page.

#Keeping it on track

Two places hold what the agent should know, and it reads both on every request without being asked.

• Instructions that always apply — Settings > Agent, the instructions box. Short standing rules: how you like things named, what to never touch, which model to prefer for what. Saved as persona.md in your workspace, so the agent can edit it for you too.
• Prompts you run again and again — the commands/ folder, one markdown file each. review.md becomes /review in the composer, and picking it drops the text in the box for you to add to before sending.
• Plans, specs and reference material — the notes/ folder in your workspace, one markdown file per topic. The agent sees every file listed by name and first line, and opens the ones that bear on what you asked for. Make the first line say what the file covers, since that is what it reads in the list. Ask the agent to write one (“put the plan in notes/”) or drop your own files in.

Prefer your own editor and coding agent? They work on the same files — see Bring your own tools.

Each installed app also carries its own AGENTS.md describing how that app is built, and the agent is given the selected app's copy, with a file pointer if it exceeds the context limit. Edit it to change how the agent works on that app — Chrysalis never overwrites a file you have changed.

#How it works

How edits reach an open app, and the tools the agent uses to check its own work, are on Live editing.

#Permissions

Full mode works without asking: it edits files across your workspace and runs shell commands. Only remote tools ask for approval. Accept mode asks before mutations, including files, skill write plans, dependency installs, and remote tools. Choose Allow once, Allow for this chat, or Skip. Chat grants are scoped to the action and target.

Plan mode keeps local tools read-only. When the plan is ready the agent shows it and asks you to accept it. Choose Accept plan and the agent carries it out in the mode you last used outside Plan, Full or Accept. Choose Keep planning, or type what to change, and it stays in Plan mode. Remote tools are exposed only when the configured server declares them read-only and not destructive; those declarations depend on the server you trust. Account creation and server changes retain their own exact-change approval.