CodeAgents Mobile

Current Limitations

• Terminal: Placeholder implementation only.
• File Editing: Currently view-only; no editing capability.
• Syntax Highlighting: Not yet implemented.
• Host Key Validation: Currently accepts all hosts.
• Offline Mode: Requires an active connection.

Future Roadmap

• Phase 1 (Terminal): Full PTY support with SwiftNIO, ANSI escape sequence processing, and command history.
• Phase 2 (Code Editor): Syntax highlighting, code completion, and multi-file editing.
• Phase 3 (Advanced): Biometric authentication, offline mode with sync, and iPad multi-window support.
• Phase 4 (Collaboration): Shared sessions and real-time collaboration.

The project uses several sources of truth for versioning depending on the build context:

• Marketing Version: Defined in VERSIONS.TXT.
• Production Artifacts (Gitea): The Gitea run number is exported as OPENCODE_PRODUCTION_ARTIFACT_RUN_NUMBER. The scripts/artifact.sh script resolves this value.
• TestFlight: Uses the resolved values passed to asc publish.
• Simulator Artifacts: Uses resolved values passed to XcodeBuildMCP as MARKETING_VERSION and CURRENT_PROJECT_VERSION overrides to ensure metadata consistency.
• Local Xcode Builds: Use the committed fallback build number. Do not use timestamp counters for local builds.

The Recurring Author Support Prompt is a non-blocking SwiftUI sheet designed to invite users to follow the author on X or provide open-source sponsorship.

Eligibility Logic

The prompt is eligible to appear only when:

1. The permanent opt-out flag is false.
2. AND either no previous presentation date exists OR at least 14 days have elapsed since the last presentation.

Persistence and Scheduling

Use UserDefaults to manage a schedule store containing:

• The most recent presentation date.
• A permanent opt-out Boolean.

Important: Record the presentation date at the moment the sheet is presented, not when it is dismissed. This prevents users from bypassing the 14-day window via crashes or force quits. Re-check eligibility when the root view first appears and whenever the scene becomes active.

To ensure that environment variables and tasks remain portable across app reinstalls, the system uses a stable proxyAgentId stored within the agent's local directory.

Identity Storage

• Path: <agent cwd>/.claude/codeagents.json
• Format: {"schema_version":1,"agent_id":"<uuid>"}

Resolution Rules

• New Agents: If the file is missing, the app creates it using the current local agent UUID.
• Reinstalls/Sync: If the file exists but the agent_id does not match the local UUID, the server agent_id wins. The app adopts the server's ID as the proxyAgentId for all subsequent proxy calls.

The duplication process handles specialized configurations as follows:

Skills Copying

For every AgentSkillAssignment associated with the source projectId:

1. A new assignment is inserted for the clone's ID.
2. AgentSkillSyncService.installSkill is called for the new clone path.
3. If a skill is missing from the global library, the process continues but returns a warning.

MCP (Model Context Protocol) Copying

1. The service fetches project-scoped servers using fetchServers(for: source, scope: .project).
2. The managed scheduler server is explicitly skipped.
3. Project-scoped servers are added to the clone using addServer(..., scope: .project, for: clone).
4. Note: Global MCP servers are not re-copied as they are already shared on the server.

Debug builds emit lightweight timing logs prefixed with [ChatRecoveryTiming] to help diagnose chat reopening and resumption performance. These logs help distinguish the costs of:

• Local SwiftData load
• Claude→OpenCode migration
• OpenCode hydration
• Persistence saves
• Media prefetch
• MCP fetch
• Resume-streaming

Note: Timing metadata is strictly limited to runtime names, operation labels, and counts. Do not include sensitive data like prompts, message text, or credentials in these logs.

The MarkdownTextView component handles link rendering by performing a two-step process: first parsing Markdown, then detecting web URLs within the resulting text.

• Explicit Markdown links: Preserve their original destinations.
• Bare URLs: Plain http:// and https:// URLs that are not part of explicit Markdown syntax are automatically detected and assigned link attributes.
• Visual Styling: All detected links are styled with the app's accent color and a single underline, applied after the base bubble color. This ensures links are distinguishable in both assistant and user message bubbles.
• URL Handling: The view uses a scoped OpenURLAction. Taps on http or https URLs are passed to UIApplication.shared.open, delegating to the system's external URL handler. Other URL schemes follow standard SwiftUI behavior.

The daemon manages pending runs to handle transient contention. To prevent replaying obsolete work, the store follows these rules:

• Keep at most one pending run per scheduled task.
• Discard pending entries older than one hour.
• Discard entries for missing tasks or disabled tasks.
• Perform a cleanup run during scheduler startup before jobs are restored to remove stale backlogs.