User guide

Getting started#

The first launch shows a six-page welcome tour. Its last page offers a starter project, a from-scratch start, or Coming from another device? — restore a .codesshbackup file or a project .zip straight away. You can replay or reset the tour later in Settings → About.

The shell

One sidebar lists the five screens — Files, Editor, Source Control, AI Assistant, Issues — and your connections below them. On iPad the sidebar sits beside the detail; on iPhone you tap through to it. Launch lands on the Main Menu by default; change that in Settings → Navigation → Sidebar Tabs → Open at Launch, where you can also reorder or hide screens. Hiding a screen keeps its ⌘-number and its palette commands working.

The sample project

A bundled project called SwiftTasks ships with real files and six seeded issues, so every screen has something in it before you write a line. Delete it whenever you like.

Two things worth doing early: set your Git identity in Settings → Git (name and email — commits made with the placeholder address are flagged), and, if you want the AI assistant, add a model in Settings → AI → Manage Models.

Projects & files#

A project is a plain folder under the app's Documents directory. There is no project file, no index and no import step — which is why the Files app can open the same folder (On My iPhone/iPad → CodeSSH), and why edits made there are the edits CodeSSH sees.

Creating one

Files → + → New Project, then pick a template: Empty, Static Website, Markdown Notes, JavaScript, Swift Script, Java, Python or SwiftUI App. Templates you save yourself appear under My Templates. For a website, New Website offers ten finished designs (portfolio, restaurant, startup, résumé and so on).

Getting code in

Import from a .zip, Clone Repository (a real git clone, submodules included), or open an external folder in place — iCloud Drive, a USB drive, an SMB share. Export the same ways: a project as a .zip, a selection as files, or straight into another project.

Living in a project

Search the tree from the browser or open the full Search screen for case-sensitive, whole-word or regular-expression matching across files, with a glob filter (.swift, src/, !.test.js) and multi-file replace. Add labels and notes, mark favourites, pin files, find duplicates, compare folders, bulk-rename, check project stats.

Deleting is reversible

Files go to a per-project Trash and projects to Recently Deleted; Settings → Trash sets how long they are kept (forever, 7, 30 or 90 days). Individual files also keep a Local History you can diff and restore.

The editor#

Tap a file to open it. Tabs run along the top: pin them, rename them, close others or to the right, reopen a closed one, or open one in the split pane or — on iPad — its own window.

Everything is in two menus

The ⋯ menu holds run and navigation, search, compare, document export, symbols and Git, and about sixty line operations. The sparkle menu holds the AI actions. The toolbar itself is customizable: pick which of AI Chat, AI Actions, Preview, Live Preview, Split Editor, Fullscreen and Save appear.

Moving around

Quick Open (⌘P), Go to Line, Outline, Go to Symbol in File, Project Symbols, Go to Definition (⌘J) or Peek Definition, Find References, Switch to Counterpart File, back and forward (⌃⌘← / ⌃⌘→), and Go to Last Edit Location (⌘U). Breadcrumbs and sticky scroll keep your place in long files.

Editing

Multiple cursors (add below/above, add next occurrence, select all occurrences, column selection, cursors to line ends), folding (at caret, others, all, by level, to MARK: sections), and a long list of line operations — comment toggles, duplicate, move, join, split, sort eight ways, convert case, align by a character, wrap a selection, reflow a paragraph, remove duplicates, filter lines. Encode and decode Base64, URLs, HTML entities, JSON strings and hashes; insert a UUID, a date, a timestamp, lorem ipsum or a colour.

Find & Replace supports case sensitivity, whole word, regular expressions, preserve case and find-in-selection, and shows "Match 3 of 17" as you go.

Renaming works in the file or across the whole project.

Split editor (⌘\) puts two files side by side; swap the panes, lock their scrolling together, drag the divider, and jump between them with ⌥⌘\.

Bookmarks, snippets, problems

Toggle a bookmark on a line and step through them; insert a snippet or save a selection as one; step through diagnostics, or open Problems and TODOs as lists. The status bar shows error and warning counts, line endings, encoding, indentation and document statistics — each of them tappable.

Nothing is lost

Unsaved work is kept as a draft and offered back after a crash or force-quit, with per-file added and removed counts.

Editor tools & file types#

The Preview control switches a file between Edit, Preview, Table, Tree and Notebook, depending on what it is.

• Markdown — a live preview with Mermaid diagrams and KaTeX math, scroll sync, Present as Slides, link checking, a table formatter and a formatting submenu (headings, lists, tasks, tables, table of contents). Mermaid and KaTeX load from a CDN, so those two need a network connection.
• JSON — a tree view, a table view, format, minify, sort keys, validate against a schema, and conversion to Swift Codable or TypeScript types.
• CSV — a table view, and conversion to and from JSON.
• Images — preview, metadata, extract a colour palette, decode Base64 images, and Import Code from Image to lift code out of a screenshot.
• SQLite — a database browser. PDF and SVG get their own previews.
• Binary files — a Quick Look preview and a searchable, editable hex dump. CodeSSH still tracks them in Git like any other file.
• Notebooks — Jupyter cells against a persistent Python session, exportable as Markdown, a script or HTML.
• Diffs — compare open tabs, the clipboard, the saved version, a Git revision, two arbitrary texts, or two folders.
• Utilities, all in the ⋯ menu — regex tester, JWT decoder, HTML entity decoder, strip HTML, remove ANSI codes, hash verifier, query-string parser, number-base converter, cron explainer, SQL formatter, YAML to JSON, timestamp converter, expression evaluator, contrast checker, colour converter, QR from selection, character inspector, word frequency and statistics.
• Sharing — export as HTML or PDF, share as an image, print, share as a GitHub gist, or copy as a Markdown code block, syntax-highlighted, or with line numbers.

Running code#

Press Run (⌘R). Four languages execute on the device, with no server:

The run console gives you stdin, Run and Stop, Run Again, run history, benchmarking, an output filter, playground-style inline results, Save Output and Explain & Fix with AI. What … Run Supports spells out the current engine's coverage.

Swift Run is an interpreter, not a compiler

It covers everyday Swift — declarations, functions and closures, control flow, operators, string interpolation, collections and a broad slice of the standard library. Anything results appear inline as you run. A run can be stopped at any time.

Python runs as real Python with the full standard library. NumPy, pandas and SciPy are available.

Tests and checks

Run Tests discovers func test…() in the open Swift file and reports pass, fail, message and duration, with a trend over time. Run All Checks re-runs every file that has a saved expected output (Run console → Save as Expected) and diffs each one.

Previews & debugging#

App Preview renders a SwiftUI file through the interpreter as a small simulator you can tap. A coverage list in the app shows which views and modifiers it renders. It adds a device frame, an inspector, snapshots and an accessibility audit.

Live web preview serves the project over a local HTTP server and shows it beside the editor: choose the default page or follow the open file, capture the JavaScript console, snapshot the result, or open it in Safari.

Serve on Local Network (in the preview's Local Network sheet) rebinds that server from loopback to every interface so a phone, tablet or laptop on the same Wi-Fi can open the address — shown as text and as a QR code. iOS asks for Local Network permission the first time. Off by default.

Debugging aids elsewhere: diagnostics and squiggles in the editor, the Problems list, breakpoint markers, run history, benchmarks and the diff tools.

Source control#

The Source Control screen talks to a real Git repository through an embedded libgit2 — the same .git folder any other Git client would use. Not a repository yet? Initialize Repository.

Committing

Stage and unstage whole files, or open a diff and stage a hunk — or tap a single changed line. Write the message yourself, pull one from a template or a recent message, dictate it, add a sign-off or a co-author, or have the AI draft one from the staged diff. Amend Last Commit fixes the last one. Commits can be signed with an SSH key.

Branching and history

Create, switch, rename, delete and prune merged branches; check out or track a remote branch. Merge, rebase — including an interactive rebase where you reorder and pick/reword before rewriting — cherry-pick a commit or a range, revert, and stash (everything, unstaged only, or with a message). Browse history with search over messages, SHAs, author:, committer: and since: (regex optional), a commit graph, per-file history, any file at any commit, blame both as a screen and as an editor gutter, compare refs, bisect, and a contribution graph.

When it goes wrong

Conflicts open a resolver with Use Ours, Use Theirs, Base and an AI Suggest Resolution; once everything is resolved you commit the merge, or abort it.

Credentials

Settings → Git → Remote Credentials holds named profiles: an HTTPS username with a personal access token, or an SSH key you paste, import or generate (with a passphrase, and a copyable public key). Profiles match by host automatically or can be pinned to a project. Everything secret goes to the iOS Keychain, and Test Credential checks it before you need it.

Host lanes

Add a GitHub, GitLab or Bitbucket connection and you also get a repository browser to clone from, pull requests (list, create — drafts included, comment, read the conversation, see changed files, merge, or check out the source branch) and host issues. GitHub adds gist sharing. Other hosts work fully for Git itself; the PR screens say plainly that they do not apply.

Also here: worktrees, submodules, Git LFS, patch export and apply, snapshot .zip export, and Review Changes with AI / Explain this commit.

Connections & terminal#

Connections live at the bottom of the sidebar. New Connection opens a gallery grouped as Git hosts, Cloud storage & files, and Servers & shells: SSH, SFTP, Telnet, WebDAV, a Files-app folder, an offline Git bundle, and the Git hosts. You can also import from an SSH config file, scan a connection QR code, or import a connections file.

Signing in

Password; an SSH key you paste, import or generate; a saved identity reused across hosts; PuTTY-format keys; or keyboard-interactive prompts for 2FA. CodeSSH tries public key, then password, then keyboard-interactive. Install Public Key on Server copies your key across for you. There is no ssh-agent support.

Host keys are pinned on first use. If one changes you get a warning screen and must explicitly choose Trust New Key & Reconnect; pinned keys can be reviewed, exported and imported.

The terminal is a full emulator, not a log view: 16-colour, 256-colour and true colour; bold, dim, italic, underline, reverse and strikethrough; scroll regions; the alternate screen (so vim, htop and less behave); bracketed paste; mouse reporting; and OSC support for window titles, the working directory, tappable hyperlinks and clipboard writes. Open several tabs, show two side by side, search output across all of them, add timestamps and highlight rules, use the custom key bar for keys the software keyboard lacks, and export a session as text, HTML or an asciinema recording. Scrollback is restored after a relaunch.

Advanced connection options: connect timeout, an HTTP CONNECT or SOCKS5 proxy, port knocking, Wake-on-LAN, jump hosts for multi-hop access (each hop gets its own trust and auth), a run-on-connect command, and environment variables. Port forwarding covers local, remote and dynamic (SOCKS5) tunnels.

Saved commands are organised in folders with variables, searchable and sortable by use, and exportable as a library. The paste guard asks before a multi-line or control-character paste reaches a shell. Ask AI drafts a command from a description.

Offline, there is still a shell

A local shell implements a large builtin set — ls, cd, cat, grep, find, sort, pipes, &&/||, aliases, history, export — plus git, swift, node, python, edit, and an issue command (issue list, issue add <title>, issue close <#N>) wired into the tracker.

Health and sharing

Rows show reachability and round-trip time (a TCP connect, not a ping), with a history sparkline; live ping is off by default because repeated probing can get you banned by fail2ban. Share as QR Code encodes the configuration only — name, host, port, username, path — and never passwords, keys or tokens.

Remote & cloud files#

SFTP

The browser lists a remote folder with multi-select. Upload and download files or whole folders, create, rename, duplicate, move, delete, change permissions, take a SHA-256 checksum, compare a remote file with a local one, search a folder tree, measure a folder's size, bookmark folders and set a default start folder. Files open straight in the editor; symlinks can be followed. Transfers show progress and can be cancelled, and they continue while the app is in the background.

Deploy Project Here diffs the open project against a remote folder into New, Changed and Remote only, optionally deletes remote-only files, and tells you when everything is already up to date.

WebDAV (Nextcloud, ownCloud and friends) browses, searches, uploads, downloads and edits the same way.

Save conflicts are never silent

If the server copy changed while you were editing, CodeSSH shows a line diff of your version against theirs and asks: Overwrite Server Copy or Keep Both.

The API client#

API Requests (Connections → ⋯, or the command palette) is a full request composer. Build collections stored per project or on the device; set a method and URL, headers, and auth as a bearer token, basic credentials or a raw Authorization header; send JSON, form or GraphQL bodies with variables.

Environments hold {{variables}} you substitute per run, and unresolved ones are named rather than sent blank. Responses open in a viewer with JSONPath extraction, and each request keeps a run history you can compare with the previous run.

Move between tools freely: Copy as cURL, Copy as Code, Paste cURL (replace), Import cURL from Clipboard, and export or import whole collections.

The WebSocket Tester (from inside API Requests, or the palette) connects with custom headers, sends text frames, logs everything with a copyable transcript, and remembers saved endpoints.

The AI assistant#

Add a model first — Settings → AI → Manage Models, or the assistant's own model menu. Three kinds:

• GGUF — runs on the llama.cpp engine bundled in the app. Download by URL (pause and resume supported), import a .gguf file, or pick from the recommended list. Nothing leaves the device.
• MLX — runs on the Apple GPU.
• External — an OpenAI-dialect or Anthropic-dialect endpoint. That covers OpenAI, Claude, OpenRouter, Together, LM Studio, Ollama and llama.cpp servers. Your API key is stored per model in the Keychain.

Each model carries its own temperature, top-p, top-k, max tokens, context window, optional system prompt and optional pricing (which turns on cost estimates). You can benchmark models against each other. A chat-template check reads a GGUF's own vocabulary and confirms it before the first reply.

Chatting

The conversation is per project and persists. The model chip at the bottom switches model, thinking depth, sampling and reply language. Start from a prompt card (Explain this file, Find bugs, Write tests, Refactor, Add docs, Explain this project) — all editable — or type.

Slash commands: /build, /issue, /create, /explain, /refactor, /tests, /fix, /doc, /review, plus custom commands you define with an {input} placeholder and can share.

Context is yours to control

Add Context… toggles the active file, open tabs, a whole-project file map, project instructions (.codessh/instructions.md), uncommitted changes and auto-included relevant files, and lets you attach specific files with a preview of exactly what the model will see. What Was Sent… then lists what was included, what was not, and what was dropped to fit the budget.

Thinking

Models that reason show a live reasoning card; set a depth per chat and a global thinking budget in tokens, and press Answer now to cut a long think short. Compute placement (Automatic / GPU only / CPU only), keep-in-memory and a performance limit are on the Models screen.

Images can be attached for vision models — from the photo library, Files or the clipboard; video is sampled into frames. Dictation and spoken replies are both available.

Managing conversations: history, pinning, bookmarked messages, Project Memory, Summarize to Memory, duplicate a chat, find within a transcript, and export or share as Markdown — one chat or all of them.

Usage (Models → Usage) estimates spend over 7 or 30 days, broken down by model, feature and agent, with CSV export.

In the editor, the same models power inline ghost completions (Tab accepts, Esc dismisses), Edit with AI, Complete at Cursor, Review Selection, Resolve TODOs and Fix with AI on a diagnostic.

The Auto-Build agent#

The agent is a bounded autonomous loop inside the chat. Give it a goal; it writes a plan, then works through the tasks — editing files in place, verifying each step, committing it to Git and narrating what it did.

Starting a run: the hammer button beside Send, /build <goal>, ⌘↵, a VoiceOver Magic Tap, or Assign to Agent on an issue. Leave the goal blank to continue the saved backlog.

While it runs, the run bar shows status, elapsed time and shipped-of-planned progress, with Pause after this step, the live activity feed, and the Plan button. The plan sheet lists every task with retry, remove and open-file, lets you add tasks (including from Issues), estimates tokens and cost, and offers Past Runs, tuning, and a build report you can copy or save into the project.

Guard rails, all in Auto-Build Agent settings: a round limit (3, 5, 10 or until you stop), an optional spend limit for priced models, a thermal pause that waits for the device to cool, plan-only runs, and agent profiles — named personas with standing instructions and their own sampling. Commit each step to git means any single step can be reverted from Source Control afterwards.

It reports as it goes

Every outcome lands in the thread, and Continue with… hands the same backlog to a different model whenever you want.

The plan and the activity feed are saved per project, so a run survives closing the app.

Issues & planning#

The Issues screen is a local tracker for the open project, stored in its .codessh/ folder. Nothing is uploaded unless you choose to push it.

The basics

Issues move Triage → Backlog → Todo → In Progress → Done, or Canceled. Swipe to advance or cancel, long-press for any status, duplicate, delete, set a due date or start a branch. Add priority, an estimate, an assignee and free-form labels (renameable across the project).

Triage is an inbox: accept, start or decline each new issue, with a duplicate hint and — if you want it — a model-backed suggestion for labels, assignee or duplicates. Suggestions are one-tap chips; nothing is applied automatically.

Planning

Milestones, a lead and a target date, project documents (specs stored under .codessh/docs/), and health updates (on track / at risk / off track) recorded in the issue history. Cycles run 1–4 weeks, roll unfinished work forward automatically, and come with burn-up and velocity charts; Insights shows throughput, time in status, and totals by label, assignee or project. SLAs set response and completion windows per priority and raise a banner and a notification when one is breached.

Structure

Sub-issues, plus blocks / blocked-by / duplicate-of relations, templates for repeated work, bulk edit, filtering and sorting (remembered per project) and CSV export of exactly the rows you are looking at.

GitHub round-trip

Import issues from the host, Push to Host to create one and stamp its number back, Start Branch… to create 123-slug from the default branch, and automatic closing when the fixing PR merges.

Everywhere else

Open issues are indexed in Spotlight; issue list|add|close works in the terminal; /issue <title> captures one from the assistant; and Assign to Agent queues a linked Auto-Build task that closes the issue when it ships.

Roadmap groups projects into initiatives with target dates across quarters.

Backup & security#

App lock

Settings → Security → Require Face ID / Touch ID locks the app whenever it goes to the background. If the device can evaluate no policy at all, the lock steps aside.

Where secrets live

Connection passwords, tokens, SSH keys and AI API keys are stored in the iOS Keychain, never in a preferences file.

The encrypted vault (Connections → Encrypted Vault…) exports connections with their secrets, SSH identities, snippets, saved commands and pinned host keys as one AES-GCM file behind a passphrase . Import merges — new items are added, existing ones kept, duplicates skipped.

Automatic backups (Settings → Backup & Restore) snapshot every project roughly every six hours and when you leave the app, keeping as many as you choose. Restore projects and settings, settings only, or projects only. They include themes, snippets, shortcuts and templates — and never API keys.

One-File Backup writes a single .codesshbackup containing all projects and settings, optionally with the encrypted vault. Restoring shows a preview with per-project selection, verifies the backup's own checksum, and never overwrites: a clashing project restores as a numbered copy. You can also back up to and restore from any Files-app folder — iCloud Drive, a USB drive.

Your files are visible

Everything is under On My iPhone/iPad → CodeSSH in the Files app. Each project also holds a .codessh/ folder for the app's own state (trash, repo data, issues, docs), which CodeSSH adds to your .gitignore and tells you it did.

If a data file goes bad, CodeSSH moves it aside as <name>.corrupt-<date> and starts fresh rather than overwriting it, and tells you in a Data Attention section in Settings.

What leaves the device: only what you set up. Local models run entirely offline; external models reach only the endpoint you configured; Git, SSH, SFTP and WebDAV reach only your hosts. There is no analytics or telemetry code. The exportable diagnostics report excludes host names, file paths, project names, connection details, credentials and file contents.

Siri, Shortcuts & automation#

App Intents — usable in Shortcuts, Siri and Focus filters: New File, Open Command Palette, Open Recent Project, Search Project, Open Project, Open File, Create Issue, Open Issues, Open Connection, Run Saved Command, Run Code, Run All Checks, Git Status, Commit Changes, Push Commits, Pull Changes, Ask Assistant. Ten come with ready-made Siri phrases ("Run code in CodeSSH"); the rest are available in the Shortcuts app.

Quick actions — long-press the app icon for New File, Command Palette and Recent Project. Reorder them in Settings → Navigation → Quick Actions, and let spare slots fill with recent projects.

Deep links — codessh://open?project=…&path=…, codessh://issue?title=…, codessh://issues, codessh://sourcecontrol, codessh://connections, codessh://build?project=… and codessh://continue. Paths that try to escape the project are rejected.

Spotlight indexes the currently open project — file names and bounded full-text content, plus open issues. Switching projects replaces the index; closing clears it.

Background work

Anything already in flight keeps going when you leave the app: clones, fetches, pushes, SFTP and WebDAV transfers, model downloads, AI replies, agent runs, backups. Turn on completion notifications in Settings → Notifications to be told when a transfer, run or build finishes.

Personalization#

Appearance — System, Light or Dark (⌃⌘A cycles), plus an accent: Monochrome (the default), Blue, Indigo, Purple, Teal, Green, Pink or Orange, previewed in light and dark side by side.

Editor themes — 309 built in, from Ayu and Dracula to Catppuccin, Nord, Everforest, GitHub and Cobalt2, searchable in a gallery. Ayu Light is the default. Edit a custom theme, import .json, .tmTheme or .xccolortheme, export your own, and pair a light theme with a dark one so the app switches automatically. The terminal has its own themes: Dark, Midnight, Matrix, Solarized, Light.

Fonts — system monospace faces, the fonts bundled with the app, and any .ttf/.otf/.ttc you import, with a programming ligatures toggle for faces that support them.

Editor behaviour — font size, line spacing, wrapping, smart editing, auto rename tag, rainbow brackets, colour swatches, diagnostic squiggles and inline messages, colourblind diff mode, relative line numbers, sticky scroll, typewriter mode, indent guides, inlay hints, reference lens, inline blame and blame gutter, column ruler, trim-on-save, final-newline-on-save, format-on-save, block cursor and a personal dictionary. Auto-save runs from 5 seconds to 5 minutes, and indentation can be overridden per project.

Navigation — reorder or hide sidebar screens, choose what opens at launch, and customise the Home-Screen quick actions.

AI preferences — the in-editor chat window and its opacity, reply statistics, suggested follow-ups, on-device stats, and inline completions with a delay (Fast / Normal / Relaxed), single-line mode and a language list.

Accessibility & languages#

• App Text Size — System, Large, Extra Large, Huge or Accessibility, applied to the app's chrome independently of iOS, while the code editor keeps its own font size.
• VoiceOver — Speak indentation depth announces "Line 42, indent 3" only when the depth changes; Speak code punctuation reads brackets, operators and colons. Terminal connection state changes are announced.
• Run-outcome sounds and haptic confirmation mark outcomes only — saves, runs, commits, a session connecting or dropping — never decoration.
• Reduce Motion is honoured throughout; animations become plain swaps.
• Preview Right-to-Left Layout mirrors the interface for RTL testing. Code, the gutter, diffs and the terminal stay left-to-right.
• Languages — System, English, Français, Deutsch, Português and 中文, with a Translation Coverage screen showing exactly what is translated.

Keyboard shortcuts#

Attach a hardware keyboard and CodeSSH behaves like a desktop editor. Press ⇧⌘/ for the cheat sheet, which lists your current bindings by category; hold ⌘ on iPad for the system overlay.

Shortcuts are fully remappable — Editor settings → Keyboard → Keyboard Shortcuts. Three presets ship: CodeSSH, Xcode-like and VS Code-like, each applied as an overlay with a diff preview first. Reset one command or all of them, and export or import a keymap file.

Defaults worth knowing:

The command palette (⇧⌘P) reaches everything else: type a few letters, use ↑/↓ and Return, Esc to close. Commands that need a project are hidden rather than shown dead, and live connections appear as "Connect: <host>".

Troubleshooting#

"No model configured." Add one in Settings → AI → Manage Models. The AI commit message, commit explanation and conflict suggestion all need a model.

An on-device reply takes a long time before the first word

Loading a multi-gigabyte model is the slow part; the pending row says which phase it is in. Keep model in memory on the Models screen avoids paying it again soon after.

"Remote File Changed" when saving over SFTP

Someone or something changed the server copy while you were editing. Compare the diff and choose Overwrite Server Copy or Keep Both.

A host key warning

The server's key changed. That is either a legitimate rebuild or something worth investigating — CodeSSH will not reconnect until you say so explicitly.

Something looks slower than usual

Settings → About shows a Conserving row when the device is hot or in Low Power Mode, naming which of the two is responsible.

A settings or data file went missing

Look for the Data Attention section in Settings: an unreadable file is set aside as <name>.corrupt-<date> rather than overwritten, so the original is still there.

Reporting a problem

Settings → About → Export Diagnostics… produces a report with launch, memory, runtime, background, storage and self-test facts and no host names, paths, project names, credentials or file contents.