{"id":45422041,"url":"https://github.com/devitools/arandu","last_synced_at":"2026-03-05T05:05:51.081Z","repository":{"id":339722086,"uuid":"1163114325","full_name":"devitools/arandu","owner":"devitools","description":"AI planning support","archived":false,"fork":false,"pushed_at":"2026-03-02T07:12:12.000Z","size":7125,"stargazers_count":3,"open_issues_count":5,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-02T11:29:00.567Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://arandu.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/devitools.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-21T05:37:42.000Z","updated_at":"2026-03-02T07:12:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/devitools/arandu","commit_stats":null,"previous_names":["devitools/markewer","devitools/arandu"],"tags_count":25,"template":false,"template_full_name":null,"purl":"pkg:github/devitools/arandu","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devitools%2Farandu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devitools%2Farandu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devitools%2Farandu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devitools%2Farandu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/devitools","download_url":"https://codeload.github.com/devitools/arandu/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devitools%2Farandu/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30111728,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-05T03:40:26.266Z","status":"ssl_error","status_checked_at":"2026-03-05T03:39:15.902Z","response_time":93,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-22T01:40:21.332Z","updated_at":"2026-03-05T05:05:51.074Z","avatar_url":"https://github.com/devitools.png","language":"TypeScript","readme":"# Arandu\n\nAn intelligent development companion — Markdown viewer, AI workspace, and plan review tool. Powered by [Tauri](https://tauri.app), [React](https://react.dev), and [GitHub Copilot](https://github.com/features/copilot).\n\n![macOS](https://img.shields.io/badge/macOS-13%2B-blue)\n![Linux](https://img.shields.io/badge/Linux-x86__64-orange)\n![Windows](https://img.shields.io/badge/Windows-x86__64-green)\n\n## Features\n\n### Document Viewing\n- GitHub Flavored Markdown rendering (tables, task lists, strikethrough, autolinks)\n- Syntax highlighting for 190+ languages\n- Sidebar outline navigation with smooth scrolling\n- Live reload on file save\n- Dark / light / system theme cycling\n\n### AI Workspace\n- **GitHub Copilot integration** via ACP (Agent Communication Protocol)\n- Multiple interaction modes: `ask`, `plan`, `code`, `edit`, `agent`, `autopilot`\n- Session management with SQLite persistence — sessions tied to workspace directories\n- Plan workflow: write a plan → review → execute, with phase tracking\n- Full streaming responses with cancel support\n\n### Plan Review \u0026 Comments\n- Inline block comments on any Markdown document\n- Comments persisted in a central SQLite database\n- Unresolved comment counters per file\n- Generate consolidated review prompts for AI tools\n\n### Voice to Text\n- Built-in offline speech transcription powered by OpenAI Whisper\n- Runs locally — no API keys, no internet required\n- 4 model sizes (tiny 75 MB to medium 1.5 GB)\n- Configurable recording shortcut and audio input device\n\n### CLI\n- `arandu README.md` — open files from terminal\n- Dual IPC transport: Unix socket (`~/.arandu/arandu.sock`) + TCP (`127.0.0.1:7474`)\n- Instant file opening if app is already running; automatic launch fallback\n- Installable via Homebrew (macOS) or manual download\n\n### System Tray\n- Persistent tray icon with custom \"A\" glyph\n- Localized menu labels (follows app language setting)\n- Closing window hides to tray instead of quitting (macOS/Linux)\n\n## Installation\n\n### macOS (Homebrew)\n\n```bash\nbrew install --cask devitools/arandu/arandu\n```\n\n### Manual Download\n\nDownload the latest release for your platform from the\n[GitHub Releases](https://github.com/devitools/arandu/releases/latest) page:\n\n| Platform | Format |\n|----------|--------|\n| macOS (Apple Silicon) | `.dmg` |\n| macOS (Intel) | `.dmg` |\n| Linux | `.AppImage`, `.deb` |\n| Windows | `.exe` |\n\n\u003e On first launch (macOS), the app offers to install the `arandu` CLI automatically.\n\u003e It can also be installed later via **Arandu → Install Command Line Tool…**\n\n## Usage\n\n### Opening Files\n\n```bash\narandu README.md           # open a single file\narandu doc1.md doc2.md     # open multiple files\narandu *.md                # open all .md files in the current directory\narandu                     # open the file picker\n```\n\n### Opening a Workspace\n\n```bash\narandu /path/to/project    # open a directory as a workspace\n```\n\nA workspace session gives you access to the GitHub Copilot chat panel, session history, and plan workflow, all scoped to that directory.\n\n## GitHub Copilot Integration\n\nArandu connects to the GitHub Copilot CLI via the **ACP (Agent Communication Protocol)** — a JSON-RPC 2.0 protocol over stdin/stdout.\n\n### Starting a Session\n\n1. Open a directory as a workspace (`arandu /path/to/project`)\n2. Click **New Session**, give it a name and an initial prompt\n3. The app spawns `gh copilot --acp --stdio` and establishes the connection\n4. Use the **Chat** tab to send messages, switch modes, or cancel generation\n\n### Interaction Modes\n\n| Mode | Description |\n|------|-------------|\n| `ask` | General questions and explanations |\n| `plan` | High-level planning and architecture |\n| `code` | Code generation and editing suggestions |\n| `edit` | Direct file edits within the workspace |\n| `agent` | Autonomous multi-step task execution |\n| `autopilot` | Fully autonomous mode |\n\n### Plan Workflow\n\n1. Use `plan` mode to generate a plan in the **Plan** tab\n2. Review and annotate the plan with inline comments\n3. Switch to `code` or `agent` mode to execute it\n4. Track execution progress in the session view\n\n## Plan Review \u0026 Comments\n\nAdd inline comments to any Markdown block, track unresolved feedback, and generate AI review prompts.\n\n**How to use:**\n- `Cmd/Ctrl+Click` any block to select it and add a comment\n- The comment panel shows all comments with block-type indicators (`H2`, `P3`, `C4`, …)\n- Resolve comments individually or generate a consolidated prompt for AI tools\n- All comments are stored in a local SQLite database (`~/.local/share/arandu/comments.db` on Linux, `~/Library/Application Support/arandu/comments.db` on macOS)\n\n## Voice to Text\n\nRecord audio and transcribe to text using OpenAI Whisper (runs entirely offline).\n\n**How to use:**\n- Press `Alt+Space` to start/stop recording (shortcut configurable in settings)\n- Choose a model size in Settings: `tiny` (fastest) to `medium` (most accurate)\n- Transcription is automatically copied to the clipboard\n- Select your audio input device from the settings panel\n\n## Development\n\n### Prerequisites\n\n- [Rust](https://www.rust-lang.org/tools/install) (stable)\n- [Node.js](https://nodejs.org) 20+\n\n### Quick Start\n\n```bash\ncd apps/tauri\nnpm install        # install frontend dependencies\nmake dev           # run in development mode (Vite + Tauri hot reload)\n```\n\n### Running Tests\n\n```bash\ncd apps/tauri\nnpm test                  # run Vitest tests\nnpm run test:coverage     # tests with coverage report\n```\n\n### Build Commands\n\n**Using Makefile (recommended):**\n\n```bash\ncd apps/tauri\nmake dev           # development mode (hot reload)\nmake build         # production build\nmake build-dev     # local dev build with git hash (e.g. Arandu_0.0.0-abc1234.dmg)\nmake install       # install app to ~/Applications + CLI to /usr/local/bin\nmake clean         # remove build artifacts\nmake help          # list all targets\n```\n\n**Using npm/npx directly:**\n\n```bash\ncd apps/tauri\nnpm run dev        # Vite dev server only (port 5173)\nnpx tauri dev      # full Tauri dev mode (Vite + Rust)\nnpx tauri build    # production build\n```\n\n### Version Management\n\n```bash\nscripts/set-version.sh 0.8.0   # update version across all config files\n```\n\n## Architecture Overview\n\n### Frontend (`apps/tauri/src/`)\n\n**Stack:** React 18 + TypeScript + Vite + TailwindCSS + shadcn/ui (Radix UI)\n\nThe app uses a **multi-window architecture** — three independent React applications sharing code:\n\n| Window | Entry | Purpose |\n|--------|-------|---------|\n| Main | `main.tsx` → `App.tsx` | Markdown viewer, workspaces, ACP chat, plan workflow |\n| Settings | `settings-main.tsx` → `SettingsApp.tsx` | Theme, language, Whisper config |\n| Whisper | `whisper-main.tsx` → `WhisperApp.tsx` | Floating voice recording UI |\n\nKey libraries:\n- **UI:** shadcn/ui components, `cn()` from `lib/utils.ts` for class merging\n- **State:** React Context (`AppContext`) + custom hooks per subsystem\n- **i18n:** i18next + react-i18next, languages `pt-BR` and `en`, cross-window sync via `localStorage`\n- **Forms:** react-hook-form + zod validation\n- **Data:** @tanstack/react-query\n- **Tests:** Vitest + React Testing Library\n\n### Backend (`apps/tauri/src-tauri/src/`)\n\n**Stack:** Rust + Tauri 2\n\n| Module | Purpose |\n|--------|---------|\n| `lib.rs` | Core commands: render markdown, file I/O, window management, tray labels |\n| `acp/` | GitHub Copilot ACP integration (JSON-RPC over stdin/stdout) |\n| `sessions.rs` | Session CRUD with SQLite persistence |\n| `comments.rs` | Block comment system with SQLite persistence |\n| `plan_file.rs` | Plan file read/write (`plans/{session_id}.md`) |\n| `history.rs` | File open history (JSON) |\n| `ipc.rs` | Unix domain socket IPC (`~/.arandu/arandu.sock`) |\n| `tcp_ipc.rs` | TCP IPC server (`127.0.0.1:7474`, all platforms) |\n| `ipc_common.rs` | Shared IPC command dispatch (`open`, `ping`, `show`) |\n| `tray.rs` | System tray icon and i18n-aware menu |\n| `cli_installer.rs` | macOS CLI installation helper |\n| `whisper/` | Offline voice transcription (model management, recording, transcription) |\n\n**Persistence:**\n- SQLite (`comments.db`): comments, file hashes, sessions — WAL mode for concurrent access\n- JSON (`history.json`): file open history\n- Markdown files (`plans/{session_id}.md`): plan documents\n\n## Contributing\n\nFor full architecture documentation, command reference, and codebase conventions, see [CLAUDE.md](./CLAUDE.md).\n\nKey points:\n- The macOS native app (`apps/macos/`) is **deprecated** — use the Tauri version only\n- Frontend is React + TypeScript — no vanilla JS, Vite handles the build\n- New Tauri commands: define in Rust → register in `invoke_handler` → add permissions to `capabilities/default.json`\n- UI components are from shadcn/ui — add new ones with `npx shadcn@latest add \u003ccomponent\u003e`\n- All user-facing strings go through `useTranslation()` and must have entries in both `locales/pt-BR.json` and `locales/en.json`\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevitools%2Farandu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdevitools%2Farandu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevitools%2Farandu/lists"}