Skip to content

Open source Grok Bot alternative, Bring your own agent and subscription: message Claude Code, Codex, Gemini CLI, Cursor, Copilot and 40+ AI agents as bots on your own computer, from iPhone, Mac, Windows, Linux or terminal. Agent-agnostic and free. Also a Muse and Dots alternative. Built in Rust.

docs: add clean code guidelines for agents

leepokai9611f7878239
diff --git a/AGENTS.md b/AGENTS.md
index bdcd3d25..7dd77865 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -43,6 +43,10 @@ Name Swift files after their main `UpperCamelCase` type; use `snake_case.rs` and
- UI controls default to the shared custom components. Explicit exception: iOS BotListView and ThreadView use native navigation/toolbar items and automatic back navigation for system Liquid Glass, as specified in `docs/design/ui-conventions.md`. The desktop app's menu bar/tray menu is the system menu. Keep system authentication and widget containers native. On iOS `.codyncSheet` presents the system sheet (grabber, swipe down). Outside these exceptions, avoid: no `Menu`/`Picker`, `.switch` toggles, `Form`/`List` styling, `confirmationDialog`/`alert`, `ProgressView`, `.sheet`/`.popover`/`.fullScreenCover`, `.toolbar`/navigation bars, `TabView`, `ContentUnavailableView`. Use `apps/ios/Kit/Sources/CodyncUI/Controls.swift` + `Chrome.swift` (`.codyncSheet`, `ModalHeader`, `ScreenHeader`, `TabBar`, `.codyncDialog`, `ToggleStyle.codync`); on the desktop, `apps/desktop/src/renderer/components/` (`Sheet`, `Dialog`, `AnchoredMenu`, `ModalHeader`, `Controls.tsx`, `Icon` for SF Symbols). Every tap that shows/hides something animates (`Motion`). Anything with a background fill gets no border line.
+## Clean code
+
+- Keep code modular and clean on every change: reuse before writing, one responsibility per file/type, no new code appended to files past ~500 lines (split first), views/components hold no I/O or logic, short single-purpose functions, enums over flags, no dead code, no swallowed errors. Full rules: [docs/guides/clean-code.md](docs/guides/clean-code.md).
+
## Cross-platform UI changes
- Any UI change in any client must include the corresponding updates to the other clients in the same change: iOS (`apps/ios/`, `apps/ios/Kit/Sources/CodyncUI/`), desktop (`apps/desktop/src/renderer/`, macOS and Linux), and terminal UI (`host/src/tui/`). This applies in every direction.
diff --git a/CLAUDE.md b/CLAUDE.md
index dee8e43a..79cec00f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -13,6 +13,10 @@ Bot-based remote for coding agents: persistent named bots on your computer, mess
- Host is Rust 2024 edition and follows the `rust-skills` rules (`~/.agents/skills/rust-skills`). Lints live in `host/Cargo.toml` (`[lints]`: default groups + pedantic, `unwrap_used`); CI runs `cargo fmt --check` and `cargo clippy --all-targets -- -D warnings`
- Host conventions: no `unwrap()` outside tests (`expect("why this can't fail")` for true invariants); lock std mutexes with `LockExt::locked()` (poison-tolerant); enums, not strings, for states and modes (`BotStatus`, `Permission`, `EntryKind`, `AlertKind`); `tracing` with structured fields (`error = format!("{e:#}")` keeps the context chain); blocking fs/process work goes through `spawn_blocking`; registry JSON is untrusted (paths are validated)
+## Clean code
+
+- Keep code modular and clean on every change: reuse before writing, one responsibility per file/type, no new code appended to files past ~500 lines (split first), views/components hold no I/O or logic, short single-purpose functions, enums over flags, no dead code, no swallowed errors. Full rules: [docs/guides/clean-code.md](docs/guides/clean-code.md).
+
## Architecture
- Clients: iOS app (SwiftUI), desktop app for macOS and Linux (`apps/desktop/`, Electron: menu bar/tray + chat window; why and how: [docs/architecture/desktop-app.md](docs/architecture/desktop-app.md)), terminal UI (`codync-host tui`, `host/src/tui/`, ratatui; layout and state vocabulary modeled on herdr). All talk to the host API.
diff --git a/docs/README.md b/docs/README.md
index 5fef09da..92dd1e99 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -18,6 +18,7 @@ Source review, a passing build, local integration tests and production acceptanc
| Change transport or cryptography | [Remote protocol](reference/remote-relay.md) and [shared vectors](reference/fixtures/README.md) |
| Change what the host and clients exchange | [Client and host compatibility](reference/compatibility.md) |
| Change an iPhone or desktop screen or button | [UI conventions](design/ui-conventions.md) |
+| Write or refactor code in any module | [Clean code](guides/clean-code.md) |
## Features
diff --git a/docs/guides/clean-code.md b/docs/guides/clean-code.md
new file mode 100644
index 00000000..fd26ab84
--- /dev/null
+++ b/docs/guides/clean-code.md
@@ -0,0 +1,38 @@
+# Clean code
+
+Rules every change follows, in every part of the repository (host, iOS, desktop, cloud, relay). Language-specific rules stay in [CLAUDE.md](../../CLAUDE.md) (Swift 6, Rust lints, TypeScript); where to put a file is in [file structure](../architecture/file-structure.md).
+
+## Before writing code
+
+- **Reuse first.** Search for an existing helper, type, component or pattern before adding one (`LockExt`, `Motion`, `Controls.swift`, `components/`, store methods). A second copy of logic that already exists is a bug waiting to diverge.
+- **Build only what is asked.** No speculative options, config for values that never change, or scaffolding "for later". No protocol/trait/interface with one implementation unless it is the test seam.
+- **Fix the root cause** in the shared function every caller goes through, not a guard at the one call site the bug report names.
+
+## Modules
+
+- **One responsibility per file and per type.** If describing a file needs "and", it is two files. Name it after that responsibility, using the shared terms from file structure.
+- **Don't grow a large file.** New behavior in a file past ~500 lines goes into a new sibling module (Rust submodule, Swift extension file, React component/hook), not appended to it. When a change already touches a large file, move the part you are changing out first, as its own `refactor` commit.
+- **Layers stay in their lane.** Views render state and send intents; stores/models own state and logic; clients/transports own I/O. No networking, persistence or parsing in a SwiftUI view or React component. In the host, keep protocol parsing, decisions and side effects (db, process, network) apart so the decision part is a pure, unit-testable function.
+- **Small public surface.** Default to `private`/`fileprivate`, `pub(crate)` or no export; widen only when another module needs it.
+- **Dependencies point one way.** `CodyncKit` never imports `CodyncUI`; renderer code reaches the host only through `window.codync`; shared code never knows about a specific screen.
+
+## Functions and types
+
+- **Short functions at one level of abstraction.** A function either orchestrates (calls named steps) or does one step, not both. Past ~40 lines or 3 levels of nesting, extract named helpers.
+- **Early return** over nested `if`/`else`; `guard` in Swift, `?`/`let … else` in Rust.
+- **Make illegal states unrepresentable.** Enums with associated data over flags, optional pairs and string states; newtypes/IDs over bare `String`/`Int` where mixing them up is possible.
+- **No magic values.** Name constants once, next to the code that owns them; reuse theme tokens instead of literal colors, spacing and durations.
+- **Pure where possible.** Pass data in and return results; keep mutation and global state at the edges.
+
+## Readability
+
+- **Names say intent**, not type or mechanics (`pendingApprovals`, not `list2` or `dataArray`). Booleans read as questions (`isConnected`, `hasUnread`).
+- **Comments explain why**, never restate what the code does. A comment that explains *what* means the code needs a better name or an extracted function.
+- **Delete dead code.** No commented-out code, unused parameters, stale feature flags or `TODO` without a reason. Git keeps the history.
+- **Errors are never swallowed.** Handle, propagate with context, or log with `tracing`/`Logger`; an empty `catch` or `let _ =` on a `Result` needs a comment saying why it is safe.
+
+## Changing existing code
+
+- Leave the code you touch a bit cleaner than you found it, but keep cleanups inside your change's area and in separate `refactor` commits from behavior changes.
+- Prefer deleting and simplifying over adding. The smallest diff that fixes the problem in the right place wins.
+- Every changed piece of logic gets a test that would fail without the change; test behavior, not private details.