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.
Rust acpagent-client-protocolai-agentsai-assistantclaudeclaude-codecodexcoding-agentscursorgeminigemini-cligrok-bot-alternativeiosiphonelinuxmacosmcpopen-sourcerustself-hosted
docs: add clean code guidelines for agents
leepokai3f869a2d609c
diff --git a/AGENTS.md b/AGENTS.mdindex 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.mdindex 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.mdindex 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) |## Featuresdiff --git a/docs/guides/clean-code.md b/docs/guides/clean-code.mdnew file mode 100644index 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.