Skip to content

feat: rewrite readme and claude.md #47

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sirily11 merged 1 commit into from
May 22, 2026
Merged

feat: rewrite readme and claude.md #47

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
183 changes: 116 additions & 67 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,91 +1,140 @@
# AGENTS.md

This file provides guidance to Codex (Codex.ai/code) when working with code in this repository. Use english for your response
This file is the canonical guidance for coding agents working in this repository. Use English for all responses and all committed project text.

## Project Overview

RxCode is a native macOS desktop client for the Codex CLI. Written in Swift + SwiftUI with two external dependencies: SwiftTerm (terminal emulation) and Sparkle (auto-update).
RxCode is a native macOS desktop client for AI coding agents. It is written in Swift and SwiftUI, with a project-centric UI for Claude Code, Codex, and Agent Client Protocol (ACP) clients. The app includes streaming chat, permission approval flows, run profiles, Git worktree support, natural-language thread search, mobile sync, and briefing/change tracking.

The main app target is a macOS app. The repository also contains shared Swift packages, widget/mobile-related code, website assets, and release tooling.

## Writing Rules

- All text committed to the project — code comments, commit messages, PR descriptions, log messages — must be written in **English**.
- Write code comments, log messages, commit messages, PR descriptions, documentation, and user-facing text in English.
- Keep documentation factual and current. Prefer removing duplicated guidance over maintaining the same instructions in multiple files.
- Preserve user changes. Do not revert unrelated local edits unless the user explicitly asks for that.
Comment on lines +13 to +15

## Build & Run
## Build And Run

```bash
# Open in Xcode (build/run with Cmd+R)
# Open in Xcode
open RxCode.xcodeproj

# CLI build
# Debug build
xcodebuild -project RxCode.xcodeproj -scheme RxCode -configuration Debug build

# Release build
xcodebuild -project RxCode.xcodeproj -scheme RxCode -configuration Release build

# Swift package build
swift build --package-path Packages

# Swift package tests
swift test --package-path Packages
```

- Minimum deployment target: macOS 26.0+
- No test suite (UI app)
- Bundle ID: `com.idealapp.RxCode`
- External dependencies: SwiftTerm (terminal emulation), Sparkle (auto-update)
Project notes:

- macOS app deployment target: macOS 26.0+
- Swift tools version: 6.2
- Main app bundle ID: `com.rxlab.RxCode`
- App-level dependencies: SwiftTerm and Sparkle
- Package dependencies: ViewInspector, Textual, and MarkdownUI

## Repository Layout

| Path | Purpose |
| --- | --- |
| `RxCode/` | macOS app target: app entry point, SwiftUI views, services, resources, and integrations. |
| `RxCode/App/` | `AppState`, app lifecycle, session handling, streaming, project/worktree logic, mobile sync dispatch, and agent coordination. |
| `RxCode/Services/` | Actor-based and service-oriented integrations for agents, permissions, GitHub, persistence, mobile sync, search, MCP, updates, and run profiles. |
| `RxCode/Views/` | SwiftUI UI surfaces: main workspace, chat, sidebar, inspector, settings, terminal, permissions, search, run profiles, and onboarding. |
| `Packages/Sources/RxCodeCore/` | Shared models, theme, utilities, run profile models, Git helpers, CLI session parsing, backend contracts, and reusable non-app UI primitives. |
| `Packages/Sources/RxCodeChatKit/` | Reusable chat UI, message rendering, input bar, slash commands, shortcuts, diffs, queue UI, and plan/question views. |
| `Packages/Sources/RxCodeSync/` | End-to-end encrypted sync protocol, pairing, APNs alert payloads, and mobile/desktop transport data structures. |
| `RxCodeWidget/` | Widget and Live Activity support for active work and usage information. |
| `RxCodeTests/`, `RxCodeUITests/` | App-level XCTest and UI test coverage. |
| `Packages/Tests/` | Swift package tests for core, chat kit, and sync logic. |
| `website/` | Public website and screenshot assets. |
| `scripts/` | Build, signing, notarization, Sparkle, and release automation. |

## Architecture

### Core Patterns

- **Observable AppState** (`App/AppState.swift`): `@MainActor @Observable` single state container. Manages all app state including projects, sessions, chat, and permission approvals.
- **App entry point** (`App/RxCodeApp.swift`): Defines WindowGroup (main), WindowGroup(id: "project-window") for dedicated per-project windows, Settings window, and Command menu (theme, update).
- **Actor-based services**: All services are implemented as `actor` for concurrency safety. Isolated without locks.
- **SwiftUI only**: No Storyboards or XIBs. 100% declarative UI.

### Package Structure

The codebase is split into two Swift packages under `Packages/`:

| Package | Role |
| --------------- | ---------------------------------------------------------------- |
| `RxCodeCore` | Shared models, theme, utilities — no UI dependencies |
| `RxCodeChatKit` | Chat UI components (ChatView, MessageBubble, InputBarView, etc.) |

### Service Layer (`Services/`)

| Service | Role |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `ClaudeService` | Spawns Codex CLI as a subprocess, parses stdout NDJSON stream, buffers text deltas at 50ms intervals |
| `PermissionServer` | Network framework-based local HTTP server (ports 19836–19846). Receives CLI PreToolUse hook requests and holds the connection until UI approval |
| `GitHubService` | OAuth Device Flow authentication, Keychain token storage, SSH key generation/registration, repo cloning |
| `PersistenceService` | JSON file-based persistence at `~/Library/Application Support/RxCode/`. Per-project/session directory structure |
| `MarketplaceService` | Parallel fetch of plugin catalog from 4 Anthropic GitHub repos, 5-minute cache |
| `RateLimitService` | Anthropic usage API polling, OAuth token refresh, usage tracking |
| `UpdateService` | Sparkle-based auto-update manager. Starts updater on launch; exposes `checkForUpdates()` for menu-initiated checks |
| `BashSafety` | Whitelist-based read-only command validator. Blocks mutating git/Codex/npm subcommands and write redirections |

### Data Flow

1. User input → `AppState.send()` → `ClaudeService.send()` spawns CLI subprocess
2. CLI stdout → NDJSON `AsyncStream<StreamEvent>` → per-event processing in `processStream()`
3. Text deltas buffered at 50ms intervals to prevent SwiftUI update thrashing
4. On tool execution: PermissionServer receives HTTP request → UI approval modal → returns response
5. On project switch: in-progress stream detached to background Task, saved to disk on completion

### View Structure (`Views/`)

- `MainView`: NavigationSplitView (sidebar + detail) with project tab bar
- `ProjectWindowView`: Dedicated single-project window (opened by double-clicking a project tab)
- `SettingsView`: App settings window (model defaults, appearance, etc.)
- `Chat/`: Main chat UI, message streaming, slash commands, attachments, marketplace, file diff, status line
- `Sidebar/`: Project list, session history, file tree, Git status, file preview, GitHub repo list
- `Onboarding/`: Initial setup flow, GitHub login
- `Permission/`: Risk-based (Safe/Moderate/High) tool approval modals
- `Terminal/`: SwiftTerm-based built-in terminal
- `UserManualView`: In-app user guide (Help menu). NavigationSplitView with topic list and detail. Topics: overview, projects, chat, shortcuts, slash commands, attachments, shortcut buttons, terminal, marketplace, permissions
- `InspectorMemoPanel`: Sidebar inspector panel with a rich-text (NSTextView) memo editor, persisted per project

### Compiler Settings

- `SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor` — default MainActor isolation
- `SWIFT_APPROACHABLE_CONCURRENCY = YES`
- App Sandbox disabled (required for system integration)

### Theme

`Theme/ClaudeTheme.swift` + `Theme/AppTheme.swift` — terracotta accent (#D97757), light/dark mode, color palette, typography, corner radius constants (8/12/16/20)
- **Observable app state**: `RxCode/App/AppState.swift` is a `@MainActor @Observable` state container. Behavior is split across `AppState+*.swift` extensions by domain.
- **SwiftUI-only UI**: Use SwiftUI views. Do not introduce Storyboards or XIBs.
- **Actor-based services**: Services that own mutable shared state should be actors or should clearly isolate concurrency through existing patterns.
- **Backend abstraction**: Claude Code, Codex, and ACP flows share backend contracts from `RxCodeCore/Backend`. Avoid adding agent-specific branches when the shared protocol can express the behavior.
- **Package boundaries**: Keep `RxCodeCore` broadly reusable and free of app-only UI dependencies. Put chat-specific SwiftUI components in `RxCodeChatKit`, sync protocol code in `RxCodeSync`, and app orchestration in `RxCode/`.

### Agent Runtime Services

| Service | Role |
| --- | --- |
| `ClaudeService` | Runs Claude Code, handles process discovery, streaming, summaries, and CLI session integration. |
| `CodexAppServer` | Runs Codex app-server sessions, parses protocol events, fetches Codex models and rate limits. |
| `ACPService` | Runs ACP clients such as OpenCode or Gemini CLI, manages pooled ACP sessions, protocol I/O, model discovery, and permission bridging. |
| `ACPRegistryService` / `ACPInstallerService` | Fetches ACP registry data and installs compatible ACP client binaries. |
| `PermissionServer` | Local HTTP server for CLI permission hooks and approval handoff to the UI. |
| `MCPService` | Reads, writes, probes, and adapts MCP server configuration for supported agent runtimes. |
| `IDEServer` tools | Exposes project/thread/search/memory tools to agents through the in-app IDE MCP server. |

### Supporting Services

| Service | Role |
| --- | --- |
| `PersistenceService` / `ThreadStore` | JSON-backed persistence under Application Support and thread/session storage. |
| `ThreadSearchService` | On-device embedding and natural-language search over chat threads. |
| `MobileSyncService` | E2E encrypted mobile pairing, relay communication, APNs fan-out, and live sync events. |
| `RunService` / `RunProfileDetector` | Run profile execution and detection for Xcode, npm, make, and shell workflows. |
| `GitHubService` | OAuth device flow, Keychain token storage, SSH key management, repository browsing, and cloning. |
| `MarketplaceService` | Skill/plugin catalog fetching and installation support. |
| `RateLimitService` | Claude usage API polling, OAuth token refresh, and usage tracking. |
| `UpdateService` | Sparkle-based update manager. |
| `BashSafety` | Read-only command validation for agent-exposed shell helpers. |

## Data Flow

1. User input enters `AppState.send(in:)`.
2. `AppState` resolves the selected agent provider, model, effort, permission mode, working directory, and optional worktree.
3. The selected backend (`ClaudeService`, `CodexAppServer`, or `ACPService`) emits an `AsyncStream<StreamEvent>`.
4. `AppState+Stream.swift` processes stream events, updates chat state, tracks tools, handles permission requests, and persists messages.
5. Permission requests route through the UI and, where needed, through `PermissionServer` or ACP/Codex protocol responses.
6. Thread summaries, branch briefings, change tracking, search indexes, widgets, and mobile snapshots update from persisted session state.

## UI Areas

- `MainView`: main `NavigationSplitView` workspace.
- `ProjectWindowView`: dedicated single-project windows.
- `Chat/` and `RxCodeChatKit`: message list, input, slash commands, attachments, plans, questions, tool output, diffs, and status UI.
- `Sidebar/`: projects, session history, briefing, file tree, Git status, GitHub repo list, and file previews.
- `Inspector/`: changes, this-thread diff, and right-side contextual panels.
- `RunProfile/`: run configuration editor, toolbar controls, and command output inspector.
- `Settings/`: agent, ACP, MCP, mobile sync, commands, memory, appearance, and related settings.
- `Terminal/`: SwiftTerm-based terminal UI.
- `Permission/`: risk-aware approval modals and queued permission banners.
- `Search/`: global natural-language search overlay.

## Implementation Guidelines

- Prefer existing app services, models, theme tokens, and helper utilities over new abstractions.
- Keep UI consistent with the established SwiftUI style and `ClaudeTheme` / `AppTheme` tokens.
- Avoid blocking the main actor with process, file, network, or parsing work.
- When adding agent features, consider Claude Code, Codex, and ACP behavior unless the feature is explicitly provider-specific.
- When changing sync payloads, preserve backward/forward compatibility where possible because mobile and desktop versions can differ.
- When changing persistence formats, add migration or tolerant decoding rather than assuming all users have fresh data.
- Use `rg` for code search and inspect surrounding code before editing.

## Testing Expectations

- For package logic, run focused `swift test --package-path Packages` tests when practical.
- For app changes, prefer focused XCTest/UI test runs if the touched area has coverage.
- For build-sensitive changes, run `xcodebuild -project RxCode.xcodeproj -scheme RxCode -configuration Debug build`.
- If you cannot run the relevant verification, state that clearly in the final response.

## Compiler And Platform Settings

- `SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor` is enabled for the app and relevant targets.
- `SWIFT_APPROACHABLE_CONCURRENCY = YES` is enabled for app/mobile-related targets.
- App Sandbox is disabled for the main macOS app because RxCode integrates with local developer tools and projects.
90 changes: 3 additions & 87 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,91 +1,7 @@
# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
This repository uses `AGENTS.md` as the canonical coding-agent guidance file.

## Project Overview
Claude Code should read [AGENTS.md](AGENTS.md) before making changes. It contains the current project overview, writing rules, build commands, architecture notes, implementation guidelines, and testing expectations.

RxCode is a native macOS desktop client for the Claude Code CLI. Written in Swift + SwiftUI with two external dependencies: SwiftTerm (terminal emulation) and Sparkle (auto-update).

## Writing Rules

- All text committed to the project — code comments, commit messages, PR descriptions, log messages — must be written in **English**.

## Build & Run

```bash
# Open in Xcode (build/run with Cmd+R)
open RxCode.xcodeproj

# CLI build
xcodebuild -project RxCode.xcodeproj -scheme RxCode -configuration Debug build

# Release build
xcodebuild -project RxCode.xcodeproj -scheme RxCode -configuration Release build
```

- Minimum deployment target: macOS 26.0+
- No test suite (UI app)
- Bundle ID: `com.idealapp.RxCode`
- External dependencies: SwiftTerm (terminal emulation), Sparkle (auto-update)

## Architecture

### Core Patterns

- **Observable AppState** (`App/AppState.swift`): `@MainActor @Observable` single state container. Manages all app state including projects, sessions, chat, and permission approvals.
- **App entry point** (`App/RxCodeApp.swift`): Defines WindowGroup (main), WindowGroup(id: "project-window") for dedicated per-project windows, Settings window, and Command menu (theme, update).
- **Actor-based services**: All services are implemented as `actor` for concurrency safety. Isolated without locks.
- **SwiftUI only**: No Storyboards or XIBs. 100% declarative UI.

### Package Structure

The codebase is split into two Swift packages under `Packages/`:

| Package | Role |
| --------------- | ---------------------------------------------------------------- |
| `RxCodeCore` | Shared models, theme, utilities — no UI dependencies |
| `RxCodeChatKit` | Chat UI components (ChatView, MessageBubble, InputBarView, etc.) |

### Service Layer (`Services/`)

| Service | Role |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `ClaudeService` | Spawns Claude CLI as a subprocess, parses stdout NDJSON stream, buffers text deltas at 50ms intervals |
| `PermissionServer` | Network framework-based local HTTP server (ports 19836–19846). Receives CLI PreToolUse hook requests and holds the connection until UI approval |
| `GitHubService` | OAuth Device Flow authentication, Keychain token storage, SSH key generation/registration, repo cloning |
| `PersistenceService` | JSON file-based persistence at `~/Library/Application Support/RxCode/`. Per-project/session directory structure |
| `MarketplaceService` | Parallel fetch of plugin catalog from 4 Anthropic GitHub repos, 5-minute cache |
| `RateLimitService` | Anthropic usage API polling, OAuth token refresh, usage tracking |
| `UpdateService` | Sparkle-based auto-update manager. Starts updater on launch; exposes `checkForUpdates()` for menu-initiated checks |
| `BashSafety` | Whitelist-based read-only command validator. Blocks mutating git/claude/npm subcommands and write redirections |

### Data Flow

1. User input → `AppState.send()` → `ClaudeService.send()` spawns CLI subprocess
2. CLI stdout → NDJSON `AsyncStream<StreamEvent>` → per-event processing in `processStream()`
3. Text deltas buffered at 50ms intervals to prevent SwiftUI update thrashing
4. On tool execution: PermissionServer receives HTTP request → UI approval modal → returns response
5. On project switch: in-progress stream detached to background Task, saved to disk on completion

### View Structure (`Views/`)

- `MainView`: NavigationSplitView (sidebar + detail) with project tab bar
- `ProjectWindowView`: Dedicated single-project window (opened by double-clicking a project tab)
- `SettingsView`: App settings window (model defaults, appearance, etc.)
- `Chat/`: Main chat UI, message streaming, slash commands, attachments, marketplace, file diff, status line
- `Sidebar/`: Project list, session history, file tree, Git status, file preview, GitHub repo list
- `Onboarding/`: Initial setup flow, GitHub login
- `Permission/`: Risk-based (Safe/Moderate/High) tool approval modals
- `Terminal/`: SwiftTerm-based built-in terminal
- `UserManualView`: In-app user guide (Help menu). NavigationSplitView with topic list and detail. Topics: overview, projects, chat, shortcuts, slash commands, attachments, shortcut buttons, terminal, marketplace, permissions
- `InspectorMemoPanel`: Sidebar inspector panel with a rich-text (NSTextView) memo editor, persisted per project

### Compiler Settings

- `SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor` — default MainActor isolation
- `SWIFT_APPROACHABLE_CONCURRENCY = YES`
- App Sandbox disabled (required for system integration)

### Theme

`Theme/ClaudeTheme.swift` + `Theme/AppTheme.swift` — terracotta accent (#D97757), light/dark mode, color palette, typography, corner radius constants (8/12/16/20)
This file intentionally delegates to `AGENTS.md` so agent instructions stay in one place.
Loading
Loading