{"id":43024481,"url":"https://github.com/eitsupi/arf","last_synced_at":"2026-05-31T10:00:53.131Z","repository":{"id":335114151,"uuid":"1133453086","full_name":"eitsupi/arf","owner":"eitsupi","description":"Alternative R Frontend — a modern R console written in Rust","archived":false,"fork":false,"pushed_at":"2026-05-31T08:16:23.000Z","size":2101,"stargazers_count":297,"open_issues_count":7,"forks_count":6,"subscribers_count":7,"default_branch":"main","last_synced_at":"2026-05-31T09:11:28.050Z","etag":null,"topics":["console","r","rust","terminal"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/eitsupi.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","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":null,"dco":null,"cla":null}},"created_at":"2026-01-13T11:16:59.000Z","updated_at":"2026-05-31T08:11:24.000Z","dependencies_parsed_at":"2026-03-11T19:02:55.084Z","dependency_job_id":null,"html_url":"https://github.com/eitsupi/arf","commit_stats":null,"previous_names":["eitsupi/arf"],"tags_count":23,"template":false,"template_full_name":null,"purl":"pkg:github/eitsupi/arf","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eitsupi%2Farf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eitsupi%2Farf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eitsupi%2Farf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eitsupi%2Farf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eitsupi","download_url":"https://codeload.github.com/eitsupi/arf/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eitsupi%2Farf/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33726719,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["console","r","rust","terminal"],"created_at":"2026-01-31T07:00:53.664Z","updated_at":"2026-05-31T10:00:53.107Z","avatar_url":"https://github.com/eitsupi.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# 🐶 arf console\n\n*Alternative R Frontend*\n\n[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/eitsupi/arf)\n\n\u003c/div\u003e\n\n\u003cbr\u003e\n\n**arf** is a cross-platform R console written in Rust.\n\n\u003e [!WARNING]\n\u003e arf is under active development. The configuration file format and history file format are not yet stable and may change without notice in future versions.\n\n\u003cdiv align=\"center\"\u003e\n\n![arf demo](demo/arf.gif)\n\n\u003c/div\u003e\n\n## Features\n\n- Single binary with no runtime dependencies\n- Cross-platform: Linux, macOS, and Windows\n- [rig](https://github.com/r-lib/rig) integration — switch R versions with `--with-r-version` or `:switch` within a session\n- Vi and Emacs editing modes\n- Multiline editing with proper indentation\n- Auto-matching brackets and quotes (with smart skip-over)\n- Tab completion for R objects, functions, and file paths inside strings\n- fzf-style history search with `Ctrl+R`; import from radian or `.Rhistory`\n- Customizable keyboard shortcuts (`Alt+-` → ` \u003c- `, `Alt+P` → ` |\u003e `)\n- Command status indicator (shows error symbol when previous command failed)\n- Fuzzy help browser with `:help` or `:h` — search across all installed packages\n- Tree-sitter based syntax highlighting with customizable colors\n- Reprex mode with optional auto-formatting via [Air](https://github.com/posit-dev/air)\n- Shell mode (`:shell` to enter, `:r` to return)\n- Configurable prompts and colors with placeholders (`{version}`, `{cwd}`, `{status}`)\n- SQLite-backed persistent history with import/export support\n- IPC server for AI agent and CI integration\n- Headless mode for non-interactive environments (CI, background jobs)\n\n## Installation\n\n### Pre-built Binaries\n\nPre-built binaries are available from [GitHub Releases](https://github.com/eitsupi/arf/releases).\n\n#### Shell Installer (Linux/macOS)\n\n```sh\ncurl --proto '=https' --tlsv1.2 -LsSf https://github.com/eitsupi/arf/releases/latest/download/arf-console-installer.sh | sh\n```\n\n#### winget (Windows)\n\n```sh\nwinget install --id eitsupi.arf\n```\n\n#### Scoop (Windows)\n\n```sh\nscoop bucket add r-bucket https://github.com/cderv/r-bucket.git\nscoop install r-bucket/arf\n```\n\n#### cargo-binstall\n\n```sh\ncargo binstall --git https://github.com/eitsupi/arf arf-console\n```\n\n#### Manual Download\n\nDownload the archive for your platform from [GitHub Releases](https://github.com/eitsupi/arf/releases) and extract the binary to a directory in your `PATH`.\n\n### Third-Party Packages\n\n[![Packaging status](https://repology.org/badge/vertical-allrepos/arf.svg)](https://repology.org/project/arf/versions)\n\n#### Homebrew (macOS/Linux)\n\n```sh\nbrew install arf\n```\n\n#### AUR (Arch Linux/Manjaro)\n\n```sh\nyay -S arf-bin\n# or use paru\nparu -S arf-bin\n```\n\n### Build from Source\n\n```sh\ncargo install --git https://github.com/eitsupi/arf.git\n```\n\n\u003e [!NOTE]\n\u003e **For Windows**: A fix for VT input handling (bracketed paste, etc.) is pending in an upstream dependency\n\u003e ([crossterm#1030](https://github.com/crossterm-rs/crossterm/pull/1030)).\n\u003e\n\u003e So installing from crates.io (`cargo install arf-console`) is **not recommended**.\n\n## Quick Start\n\n```sh\n# Launch arf\narf\n\n# Use a specific R version (requires rig)\narf --with-r-version 4.4\n\n# Enable reprex mode for reproducible examples\narf --reprex\n```\n\n### Interactive Help\n\nPress `:h` or `:help` to open the fuzzy help browser:\n\n```\n─ Help Search [12345 topics] ─────────────────────────\n  Filter: mutate_\n\n \u003e dplyr::mutate           Create, modify, and delete columns\n   dplyr::mutate_all       Mutate multiple columns\n   dplyr::mutate_at        Mutate multiple columns\n   dplyr::mutate_if        Mutate multiple columns\n─────────────────────────────────────────────────────\n  ↑↓ navigate  Tab/Enter select  Esc exit\n```\n\n## Meta Commands\n\narf extends R with `:` prefixed meta commands:\n\n| Command | Description |\n|---------|-------------|\n| `:help`, `:h` | Open interactive help browser |\n| `:info`, `:session` | Show session information (version, config path, etc.) |\n| `:shell` | Enter shell mode |\n| `:r` | Return to R mode |\n| `:system \u003ccmd\u003e` | Execute a single shell command inline |\n| `:reprex` | Toggle reprex mode |\n| `:autoformat`, `:format` | Toggle auto-formatting (requires Air) |\n| `:switch \u003cversion\u003e` | Restart with different R version (requires rig) |\n| `:restart` | Restart R session |\n| `:cd [path]` | Change working directory (no args → home) |\n| `:pushd \u003cpath\u003e` | Push current directory to stack and change to path |\n| `:popd` | Pop directory from stack and change to it |\n| `:history browse` | Browse and manage command history |\n| `:history clear` | Clear command history (supports `r`, `shell`, `all` targets) |\n| `:history schema` | Display history database schema and R examples |\n| `:commands`, `:cmds` | Show available commands |\n| `:quit`, `:exit` | Exit arf |\n\n\u003e [!NOTE]\n\u003e **Experimental:** Enable the `experimental.shell_semicolon_shortcut` option to switch to shell mode by pressing `;` at an empty prompt — no `:shell` or Enter required (similar to Julia REPL behavior).\n\n## Configuration\n\narf uses a TOML configuration file located at:\n\n- **Linux**: `~/.config/arf/arf.toml`\n- **macOS**: `~/Library/Application Support/arf/arf.toml`\n- **Windows**: `%APPDATA%\\arf\\arf.toml`\n\nGenerate a default configuration with:\n\n```sh\narf config init\n```\n\n### Example Configuration\n\n```toml\n[startup]\nr_source = \"auto\"       # \"auto\", \"rig\", or { path = \"/path/to/R\" }\nshow_banner = true\n\n# Initial mode settings (can be toggled at runtime)\n[startup.mode]\nreprex = false\nautoformat = false      # Requires Air CLI\n\n[editor]\nmode = \"emacs\"          # \"emacs\" or \"vi\"\nauto_match = true       # Auto-close brackets and quotes\nauto_suggestions = \"all\" # \"none\", \"all\", or \"cwd\"\n\n# Keyboard shortcuts (crokey format)\n[editor.key_map]\nalt-hyphen = \" \u003c- \"\nalt-p = \" |\u003e \"          # Use \"ctrl-shift-m\" for RStudio-style\n\n[prompt]\nformat = \"{status}R {version}\u003e \"\ncontinuation = \"+  \"\nshell_format = \"[{shell}] $ \"\nmode_indicator = \"prefix\"   # \"prefix\", \"suffix\", or \"none\"\n\n# Command status indicator\n[prompt.status]\nsymbol = { error = \"✗ \" }   # success = \"\" (empty) by default\noverride_prompt_color = false\n\n# R runtime configuration\n[r]\nauto_width = true       # Sync options(width) with terminal size\n\n# Reprex static configuration\n[mode.reprex]\ncomment = \"#\u003e \"\n\n# Syntax highlighting colors\n[colors.r]\nkeyword = \"LightBlue\"\nstring = \"Green\"\ncomment = \"DarkGray\"\nnumber = \"LightMagenta\"\noperator = \"Yellow\"\n\n[colors.prompt]\nmain = \"LightGreen\"\n```\n\nSee the full [Configuration Guide](docs/configuration.md) for all options.\n\n## Headless Mode \u0026 IPC\n\n\u003e [!NOTE]\n\u003e This feature is experimental and may change in future versions.\n\nRun R without a terminal and interact via IPC — useful for AI agents, CI, and editor extensions. Unlike MCP-based solutions that require R package installation and an MCP client, arf provides a single binary with a simple CLI for programmatic R access:\n\n```sh\n# Start headless R with IPC server\narf headless\n\n# From another terminal, evaluate R code\narf ipc eval '1 + 1'\n\n# Get session info as JSON\narf ipc session | jq '.r.version'\n\n# Shut down when done\narf ipc shutdown\n```\n\nSee the full [IPC \u0026 Headless Mode Guide](docs/ipc.md) for details.\n\n## Experimental Features\n\nFeatures in this section are under development and may change or be removed in future versions. Configure them under the `[experimental]` table and its subtables (e.g. `[experimental.prompt_spinner]`).\n\n### Spinner\n\nDisplays an animated spinner at the start of the line while R is evaluating code. **Disabled by default.**\n\nTo enable, set the `frames` option:\n\n```toml\n[experimental.prompt_spinner]\nframes = \"⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏\"  # Braille dots\ncolor = \"Cyan\"              # Spinner color (default: Cyan)\n```\n\nSee [Spinner configuration](docs/configuration.md#spinner) for all options and frame style examples.\n\n### Auto-completion while typing\n\nShow the completion menu automatically after typing a minimum number of characters, without requiring Tab.\n\n```toml\n[experimental]\ncompletion_min_chars = 3  # Show completions after 3 characters\n```\n\nWhen not set, completion requires pressing Tab (the default behavior). This is similar to radian's `complete_while_typing` feature.\n\n### Fuzzy R completion\n\nUse fuzzy matching for R code completions. When enabled, typing `sf::geo` can match `sf::st_geometry` and `library(dpl` can match `dplyr`. **Disabled by default.**\n\n```toml\n[experimental.r_completion]\nfuzzy = true\n```\n\nBoth `::` (exported names) and `:::` (internal names) are supported. Package exports are cached per-package with a 5-minute TTL for performance.\n\nSee [Fuzzy R Completion configuration](docs/configuration.md#fuzzy-r-completion) for the `package_functions` option and other details.\n\n### History forget\n\nAutomatically remove commands that produced errors from history. Similar to fish's [sponge](https://github.com/meaningful-ooo/sponge) plugin.\n\n```toml\n[experimental.history_forget]\nenabled = true\ndelay = 2          # Keep last N failed commands for quick retry\non_exit_only = false  # Purge on each prompt (false) or only on exit (true)\n```\n\nSee [History forget configuration](docs/configuration.md#history-forget) for all options.\n\n### History export/import\n\n\u003e [!CAUTION]\n\u003e These features are experimental and have not been thoroughly tested. The format and behavior may change in future versions.\n\n#### Export\n\nExport both R and shell history to a unified SQLite file for backup or transfer:\n\n```sh\n# Export to a unified file\narf history export --file ~/arf_backup.db\n\n# Export with custom table names\narf history export --file ~/arf_backup.db --r-table my_r --shell-table my_shell\n```\n\n**Options:**\n\n| Option | Description |\n|--------|-------------|\n| `--file` | Path to output SQLite file (required) |\n| `--r-table` | Table name for R history (default: `r`) |\n| `--shell-table` | Table name for shell history (default: `shell`) |\n\n#### Import\n\nImport command history from radian, R's native `.Rhistory`, or another arf database:\n\n```sh\n# Preview what would be imported (dry run)\narf history import --from radian --dry-run\n\n# Import from radian (default: ~/.radian_history)\narf history import --from radian\n\n# Import from R's native history\narf history import --from r --file .Rhistory\n\n# Import from a unified export file (restores both R and shell history)\narf history import --from arf --file ~/arf_backup.db\n\n# Import from a single-database file (r.db or shell.db)\narf history import --from arf --file /path/to/r.db\n\n# Import with custom hostname (to distinguish from native entries)\narf history import --from radian --hostname \"radian-import\"\n```\n\n**Options:**\n\n| Option | Description |\n|--------|-------------|\n| `--from` | Source format: `radian`, `r`, or `arf` (required) |\n| `--file` | Path to source file (required for `arf`, defaults to standard locations for others) |\n| `--hostname` | Custom hostname to mark imported entries |\n| `--dry-run` | Preview without importing |\n| `--import-duplicates` | Import duplicate entries instead of skipping them |\n| `--unified` | Force unified file mode (import both R and shell from table names) |\n| `--r-table` | Table name for R history in unified file (default: `r`) |\n| `--shell-table` | Table name for shell history in unified file (default: `shell`) |\n\n**Supported sources:**\n\n| Source | Description | Timestamps | Multiline | Mode routing |\n|--------|-------------|:----------:|:---------:|:------------:|\n| `radian` | `~/.radian_history` | Preserved | Preserved | By `# mode:` |\n| `r` | `.Rhistory` or `R_HISTFILE` | - | - | → `r.db` |\n| `arf` | SQLite database (`--file` required) | Preserved | Preserved | By filename or `--unified` |\n\n**Mode routing for arf format:**\n\n- Files named `r.db` or `shell.db`: Single-database import (by filename)\n- Other filenames or `--unified` flag: Unified import (by table names, imports both R and shell)\n\n**Notes:**\n\n- By default, duplicate entries are skipped during import (matched by command text and timestamp). Use `--import-duplicates` to import all entries regardless.\n- Self-import is detected and rejected when importing from an arf database to the same target file.\n- **Important:** Exit arf before exporting to ensure the source databases are in a consistent state. The export itself uses atomic writes to prevent incomplete output files, but reading while arf is writing may capture inconsistent data.\n\n## Known Issues\n\n### Error detection uses `options(error = ...)`\n\narf uses R's `options(error = ...)` to detect errors from packages like dplyr/rlang that output error messages to stdout instead of stderr. This is necessary for accurate error tracking in command history and the status indicator.\n\n**Limitations**:\n- If you set a custom error handler via `options(error = ...)`, arf will chain to your handler, but arf's handler takes precedence. Your handler will still be called after arf records the error.\n- There is a slight performance overhead (~microseconds) on each prompt due to R API calls for checking and resetting error state. This is negligible in practice but may be noticeable in benchmarks.\n\n## Related Projects\n\n- [radian](https://github.com/randy3k/radian) — A 21st century R console written in Python. arf draws inspiration from radian's design philosophy.\n\n- [sircon](https://github.com/lrberge/sircon) — Simple R Console. A Windows-only R console with powerful autocomplete and a macro language for custom shortcuts. Some of sircon's advanced features are future goals for arf.\n\n## Acknowledgements\n\narf is built upon the broad Rust ecosystem and the remarkable efforts of those who have created open-source tools for R. In particular, we would like to highlight the following projects:\n\n- **[ark](https://github.com/posit-dev/ark)** — The `arf-libr` and `arf-harp` crates are derived from ark's `libr` and `harp` crates, which provide the foundation for embedding R in Rust applications. Windows initialization follows ark's pattern. [tree-sitter-r](https://github.com/r-lib/tree-sitter-r) powers syntax highlighting and code analysis.\n\n- **[radian](https://github.com/randy3k/radian)** — arf's design and many features are inspired by radian, including shell mode, stderr formatting, and tab completion patterns. The feedback and discussions in radian's GitHub issues over the years have also been invaluable.\n\n- **[felp](https://github.com/atusy/felp)** — The interactive fuzzy help browser concept was inspired by felp's `fuzzyhelp()` function.\n\n- **[reedline](https://github.com/nushell/reedline)** — The line editor library from the Nushell project that powers arf's interactive editing.\n\n- **[mcp-repl](https://github.com/t-kalinowski/mcp-repl)** — The headless mode's pager redirection and graphics device configuration are based on mcp-repl's approach for non-interactive R sessions.\n\n- **[MCPRepl.jl](https://github.com/hexaeder/MCPRepl.jl)** / **[Kaimon.jl](https://github.com/kahliburke/Kaimon.jl)** — The IPC server design (shared REPL with agent code visibility, synchronous evaluation via backend queue) was heavily informed by these Julia MCP server implementations.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feitsupi%2Farf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feitsupi%2Farf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feitsupi%2Farf/lists"}