{"id":48653035,"url":"https://github.com/shantanugoel/rust-bash","last_synced_at":"2026-04-10T08:55:40.834Z","repository":{"id":345715481,"uuid":"1187039954","full_name":"shantanugoel/rust-bash","owner":"shantanugoel","description":"A sandboxed bash interpreter for AI Agents, built in Rust","archived":false,"fork":false,"pushed_at":"2026-04-05T02:25:51.000Z","size":4017,"stargazers_count":8,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-10T08:55:36.786Z","etag":null,"topics":["agents","ai","ai-agents","bash","rust","shell"],"latest_commit_sha":null,"homepage":"https://rustbash.dev/","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/shantanugoel.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-03-20T09:18:03.000Z","updated_at":"2026-04-06T14:18:18.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/shantanugoel/rust-bash","commit_stats":null,"previous_names":["shantanugoel/rust-bash"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/shantanugoel/rust-bash","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shantanugoel%2Frust-bash","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shantanugoel%2Frust-bash/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shantanugoel%2Frust-bash/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shantanugoel%2Frust-bash/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shantanugoel","download_url":"https://codeload.github.com/shantanugoel/rust-bash/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shantanugoel%2Frust-bash/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31635969,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-10T07:40:12.752Z","status":"ssl_error","status_checked_at":"2026-04-10T07:40:11.664Z","response_time":98,"last_error":"SSL_read: 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":["agents","ai","ai-agents","bash","rust","shell"],"created_at":"2026-04-10T08:55:39.405Z","updated_at":"2026-04-10T08:55:40.772Z","avatar_url":"https://github.com/shantanugoel.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# rust-bash\n\nA sandboxed bash interpreter for AI Agents, built in Rust. Execute bash scripts safely with a virtual filesystem — no containers, no VMs, no host access.\n\n### 🌐 [Try it in the browser →](https://rustbash.dev)\n\nInteractive showcase with 80+ commands running via WASM. Includes an AI agent you can talk to. See [`examples/website/`](examples/website/) for the source.\n\n## Highlights\n\n- **Virtual filesystem** — all file operations happen in memory by default. No host files are touched.\n- **80 commands** — echo, cat, grep, awk, sed, jq, find, sort, diff, curl, and many more.\n- **Full bash syntax** — pipelines, redirections, variables, control flow, functions, command substitution, globs, brace expansion, arithmetic, here-documents, case statements.\n- **Execution limits** — 10 configurable bounds (time, commands, loops, output size, call depth, string length, glob results, substitution depth, heredoc size, brace expansion).\n- **Network policy** — sandboxed `curl` with URL allow-lists, method restrictions, redirect and response-size limits.\n- **Multiple filesystem backends** — InMemoryFs (default), OverlayFs (copy-on-write), ReadWriteFs (passthrough), MountableFs (composite).\n- **npm package** — `rust-bash` with TypeScript types, native Node.js addon, and WASM support.\n- **AI tool integration** — framework-agnostic JSON Schema tool definitions for OpenAI, Anthropic, Vercel AI SDK, LangChain.js.\n- **MCP server** — built-in Model Context Protocol server for Claude Desktop, Cursor, VS Code.\n- **Embeddable** — use as a Rust crate with a builder API. Custom commands via the `VirtualCommand` trait.\n- **CLI binary** — standalone `rust-bash` command with `-c`, `--files`, `--env`, `--cwd`, `--json` flags, MCP server mode, and an interactive REPL.\n\n## Installation\n\n### npm (TypeScript / JavaScript)\n\n```bash\nnpm install rust-bash\n```\n\n### Rust crate\n\n```bash\ncargo add rust-bash\n```\n\n### Build from source (Rust)\n\n```bash\ngit clone https://github.com/shantanugoel/rust-bash.git\ncd rust-bash\ncargo build --release\n# Binary is at target/release/rust-bash\n```\n\n### Install via Cargo\n\n```bash\ncargo install rust-bash\n```\n\n## Quick Start (TypeScript)\n\n```typescript\nimport { Bash, tryLoadNative, createNativeBackend, initWasm, createWasmBackend } from 'rust-bash';\n\n// Auto-detect backend: native addon (fast) or WASM (universal)\nlet createBackend;\nif (await tryLoadNative()) {\n  createBackend = createNativeBackend;\n} else {\n  await initWasm();\n  createBackend = createWasmBackend;\n}\n\nconst bash = await Bash.create(createBackend, {\n  files: {\n    '/data.json': '{\"name\": \"world\"}',\n    '/script.sh': 'echo \"Hello, $(jq -r .name /data.json)!\"',\n  },\n  env: { USER: 'agent' },\n});\n\nconst result = await bash.exec('bash /script.sh');\nconsole.log(result.stdout);   // \"Hello, world!\\n\"\nconsole.log(result.exitCode); // 0\n```\n\n## Quick Start (Rust)\n\n```rust\nuse rust_bash::RustBashBuilder;\nuse std::collections::HashMap;\n\nlet mut shell = RustBashBuilder::new()\n    .files(HashMap::from([\n        (\"/data.txt\".into(), b\"hello world\".to_vec()),\n    ]))\n    .env(HashMap::from([\n        (\"USER\".into(), \"agent\".into()),\n    ]))\n    .build()\n    .unwrap();\n\nlet result = shell.exec(\"cat /data.txt | grep hello\").unwrap();\nassert_eq!(result.stdout, \"hello world\\n\");\nassert_eq!(result.exit_code, 0);\n```\n\n## Custom Commands\n\n### TypeScript\n\n```typescript\nimport { Bash, defineCommand } from 'rust-bash';\n\nconst fetch = defineCommand('fetch', async (args, ctx) =\u003e {\n  const url = args[0];\n  const response = await globalThis.fetch(url);\n  return { stdout: await response.text(), stderr: '', exitCode: 0 };\n});\n\nconst bash = await Bash.create(createBackend, {\n  customCommands: [fetch],\n});\n\nawait bash.exec('fetch https://api.example.com/data');\n```\n\n### Rust\n\n```rust\nuse rust_bash::{RustBashBuilder, VirtualCommand, CommandContext, CommandResult};\n\nstruct MyCommand;\n\nimpl VirtualCommand for MyCommand {\n    fn name(\u0026self) -\u003e \u0026str { \"my-cmd\" }\n    fn execute(\u0026self, args: \u0026[String], ctx: \u0026CommandContext) -\u003e CommandResult {\n        CommandResult {\n            stdout: format!(\"got {} args\\n\", args.len()),\n            ..Default::default()\n        }\n    }\n}\n\nlet mut shell = RustBashBuilder::new()\n    .command(Box::new(MyCommand))\n    .build()\n    .unwrap();\n\nlet result = shell.exec(\"my-cmd foo bar\").unwrap();\nassert_eq!(result.stdout, \"got 2 args\\n\");\n```\n\n## AI Tool Integration\n\n`rust-bash` exports framework-agnostic tool primitives — use with any AI agent framework:\n\n```typescript\nimport {\n  bashToolDefinition,\n  createBashToolHandler,\n  formatToolForProvider,\n  createNativeBackend,\n} from 'rust-bash';\n\nconst { handler } = createBashToolHandler(createNativeBackend, {\n  files: { '/data.txt': 'hello world' },\n  maxOutputLength: 10000,\n});\n\n// Format for your provider\nconst openaiTool = formatToolForProvider(bashToolDefinition, 'openai');\nconst anthropicTool = formatToolForProvider(bashToolDefinition, 'anthropic');\n\n// Handle tool calls from the LLM\nconst result = await handler({ command: 'grep hello /data.txt' });\n// { stdout: 'hello world\\n', stderr: '', exitCode: 0 }\n```\n\n### OpenAI\n\n```typescript\nimport OpenAI from 'openai';\nimport { createBashToolHandler, formatToolForProvider, bashToolDefinition, createNativeBackend } from 'rust-bash';\n\nconst { handler } = createBashToolHandler(createNativeBackend, { files: myFiles });\nconst openai = new OpenAI();\n\nconst response = await openai.chat.completions.create({\n  model: 'gpt-4o',\n  tools: [formatToolForProvider(bashToolDefinition, 'openai')],\n  messages: [{ role: 'user', content: 'Count lines in /data.txt' }],\n});\n\nfor (const toolCall of response.choices[0].message.tool_calls ?? []) {\n  const result = await handler(JSON.parse(toolCall.function.arguments));\n}\n```\n\n### Anthropic\n\n```typescript\nimport Anthropic from '@anthropic-ai/sdk';\nimport { createBashToolHandler, formatToolForProvider, bashToolDefinition, createNativeBackend } from 'rust-bash';\n\nconst { handler } = createBashToolHandler(createNativeBackend, { files: myFiles });\nconst anthropic = new Anthropic();\n\nconst response = await anthropic.messages.create({\n  model: 'claude-sonnet-4-20250514',\n  max_tokens: 1024,\n  tools: [formatToolForProvider(bashToolDefinition, 'anthropic')],\n  messages: [{ role: 'user', content: 'Count lines in /data.txt' }],\n});\n\nfor (const block of response.content) {\n  if (block.type === 'tool_use') {\n    const result = await handler(block.input);\n  }\n}\n```\n\n### Vercel AI SDK\n\n```typescript\nimport { tool } from 'ai';\nimport { z } from 'zod';\nimport { createBashToolHandler, createNativeBackend } from 'rust-bash';\n\nconst { handler } = createBashToolHandler(createNativeBackend, { files: myFiles });\nconst bashTool = tool({\n  description: 'Execute bash commands in a sandbox',\n  parameters: z.object({ command: z.string() }),\n  execute: async ({ command }) =\u003e handler({ command }),\n});\n```\n\n### LangChain.js\n\n```typescript\nimport { tool } from '@langchain/core/tools';\nimport { z } from 'zod';\nimport { createBashToolHandler, createNativeBackend } from 'rust-bash';\n\nconst { handler, definition } = createBashToolHandler(createNativeBackend, { files: myFiles });\nconst bashTool = tool(\n  async ({ command }) =\u003e JSON.stringify(await handler({ command })),\n  { name: definition.name, description: definition.description, schema: z.object({ command: z.string() }) },\n);\n```\n\nSee [AI Agent Tool Recipe](docs/recipes/ai-agent-tool.md) for complete agent loop examples.\n\n## MCP Server\n\nThe CLI binary includes a built-in [Model Context Protocol](https://modelcontextprotocol.io/) server:\n\n```bash\nrust-bash --mcp\n```\n\nExposed tools: `bash`, `write_file`, `read_file`, `list_directory`. State persists across calls.\n\n### Claude Desktop\n\n```json\n{\n  \"mcpServers\": {\n    \"rust-bash\": {\n      \"command\": \"rust-bash\",\n      \"args\": [\"--mcp\"]\n    }\n  }\n}\n```\n\n### VS Code (GitHub Copilot)\n\n```json\n{\n  \"servers\": {\n    \"rust-bash\": {\n      \"type\": \"stdio\",\n      \"command\": \"rust-bash\",\n      \"args\": [\"--mcp\"]\n    }\n  }\n}\n```\n\nSee [MCP Server Setup](docs/recipes/mcp-server.md) for Cursor, Windsurf, Cline, and other clients.\n\n## Browser / WASM\n\n```typescript\nimport { Bash, initWasm, createWasmBackend } from 'rust-bash/browser';\n\nawait initWasm();\nconst bash = await Bash.create(createWasmBackend, {\n  files: { '/hello.txt': 'Hello from WASM!' },\n});\n\nconst result = await bash.exec('cat /hello.txt');\nconsole.log(result.stdout); // \"Hello from WASM!\\n\"\n```\n\n## Performance\n\n| Feature | just-bash | rust-bash |\n|---------|-----------|-----------------|\n| Language | Pure TypeScript | Rust → WASM + native addon |\n| Performance | JS-speed | Near-native (native addon) / WASM |\n| API | `new Bash(opts)` | `Bash.create(backend, opts)` |\n| Custom commands | `defineCommand()` | `defineCommand()` (same API) |\n| AI integration | Vercel AI SDK only | Framework-agnostic (OpenAI, Anthropic, Vercel, LangChain) |\n| MCP server | ❌ | ✅ Built-in (`rust-bash --mcp`) |\n| Browser | ✅ | ✅ (WASM) |\n| Node.js native | ❌ | ✅ (napi-rs) |\n| C FFI | ❌ | ✅ (shared library) |\n| Filesystem backends | In-memory only | InMemoryFs, OverlayFs, ReadWriteFs, MountableFs |\n| Execution limits | ✅ | ✅ (10 configurable bounds) |\n| Network policy | ❌ | ✅ (URL allow-list, method restrictions) |\n\n## CLI Binary\n\n```bash\n# Execute a command\nrust-bash -c 'echo hello | wc -c'\n\n# Seed files from host disk into the virtual filesystem\nrust-bash --files /path/to/data.txt:/data.txt -c 'cat /data.txt'\nrust-bash --files /path/to/dir -c 'ls /'\n\n# Set environment variables\nrust-bash --env USER=agent --env HOME=/home/agent -c 'echo $USER'\n\n# Set working directory\nrust-bash --cwd /app -c 'pwd'\n\n# JSON output for machine consumption\nrust-bash --json -c 'echo hello'\n# {\"stdout\":\"hello\\n\",\"stderr\":\"\",\"exit_code\":0}\n\n# Execute a script file with positional arguments\nrust-bash script.sh arg1 arg2\n\n# Read commands from stdin\necho 'echo hello' | rust-bash\n\n# MCP server mode\nrust-bash --mcp\n\n# Interactive REPL (starts when no command/script/stdin is given)\nrust-bash\n```\n\n### Interactive REPL\n\nWhen launched without `-c`, a script file, or piped stdin, `rust-bash` starts an\ninteractive REPL with readline support:\n\n- **Colored prompt** — `rust-bash:{cwd}$ ` reflecting the current directory, green (exit 0) or red (non-zero last exit)\n- **Tab completion** — completes built-in command names\n- **Multi-line input** — incomplete constructs (e.g., `if true; then`) wait for more input\n- **History** — persists across sessions in `~/.rust_bash_history`\n- **Ctrl-C** — cancels the current input line\n- **Ctrl-D** — exits the REPL with the last command's exit code\n- **`exit [N]`** — exits with code N (default 0)\n\n## Use Cases\n\n- **AI agent tools** — give LLMs a bash sandbox without container overhead\n- **Code sandboxes** — run user-submitted scripts safely\n- **Testing** — deterministic bash execution with a controlled filesystem\n- **Embedded scripting** — add bash scripting to Rust applications\n- **MCP server** — provide bash execution to Claude Desktop, Cursor, VS Code\n\n## Built-in Commands\n\n### Registered commands (80)\n\n| Category | Commands |\n|----------|----------|\n| **Core** | `echo`, `cat`, `true`, `false`, `pwd`, `touch`, `mkdir`, `ls`, `test`, `[` |\n| **File ops** | `cp`, `mv`, `rm`, `tee`, `stat`, `chmod`, `ln`, `readlink`, `rmdir`, `du`, `split` |\n| **Text** | `grep`, `egrep`, `fgrep`, `sort`, `uniq`, `cut`, `head`, `tail`, `wc`, `tr`, `rev`, `fold`, `nl`, `printf`, `paste`, `od`, `tac`, `comm`, `join`, `fmt`, `column`, `expand`, `unexpand`, `strings` |\n| **Text processing** | `sed`, `awk`, `jq`, `diff` |\n| **Search** | `rg` |\n| **Navigation** | `realpath`, `basename`, `dirname`, `tree`, `find` |\n| **Utilities** | `expr`, `date`, `sleep`, `seq`, `env`, `printenv`, `which`, `base64`, `md5sum`, `sha1sum`, `sha256sum`, `whoami`, `hostname`, `uname`, `yes`, `xargs`, `timeout`, `file`, `bc`, `clear` |\n| **Compression** | `gzip`, `gunzip`, `zcat`, `tar` |\n| **Network** | `curl` *(feature-gated)* |\n\nAll commands support `--help` for built-in usage information.\n\n### Interpreter builtins (40)\n\n`exit`, `cd`, `export`, `unset`, `set`, `shift`, `readonly`, `declare`, `read`, `eval`, `source` / `.`, `break`, `continue`, `:` / `colon`, `let`, `local`, `return`, `trap`, `shopt`, `type`, `command`, `builtin`, `getopts`, `mapfile` / `readarray`, `pushd`, `popd`, `dirs`, `hash`, `wait`, `alias`, `unalias`, `printf`, `exec`, `sh` / `bash`, `help`, `history`\n\nAdditionally, `if`/`then`/`elif`/`else`/`fi`, `for`/`while`/`until`/`do`/`done`, `case`/`esac`, `((...))`, `[[ ]]`, and `time` are handled as shell syntax by the interpreter.\n\n## Configuration (Rust)\n\n```rust\nuse rust_bash::{RustBashBuilder, ExecutionLimits, NetworkPolicy};\nuse std::collections::HashMap;\nuse std::time::Duration;\n\nlet mut shell = RustBashBuilder::new()\n    .files(HashMap::from([\n        (\"/app/script.sh\".into(), b\"echo hello\".to_vec()),\n    ]))\n    .env(HashMap::from([\n        (\"HOME\".into(), \"/home/agent\".into()),\n    ]))\n    .cwd(\"/app\")\n    .execution_limits(ExecutionLimits {\n        max_command_count: 1_000,\n        max_execution_time: Duration::from_secs(5),\n        ..Default::default()\n    })\n    .network_policy(NetworkPolicy {\n        enabled: true,\n        allowed_url_prefixes: vec![\"https://api.example.com/\".into()],\n        ..Default::default()\n    })\n    .build()\n    .unwrap();\n```\n\n\u003e **Tip:** To allow all URLs, set `allowed_url_prefixes` to `vec![\"http://\".into(), \"https://\".into()]`.\n\u003e Wildcards are not supported — the policy uses prefix matching.\n\n### Execution limits defaults\n\n| Limit | Default |\n|-------|---------|\n| `max_call_depth` | 25 |\n| `max_command_count` | 10,000 |\n| `max_loop_iterations` | 10,000 |\n| `max_execution_time` | 30 s |\n| `max_output_size` | 10 MB |\n| `max_string_length` | 10 MB |\n| `max_glob_results` | 100,000 |\n| `max_substitution_depth` | 50 |\n| `max_heredoc_size` | 10 MB |\n| `max_brace_expansion` | 10,000 |\n\n## Filesystem Backends\n\n| Backend | Description |\n|---------|-------------|\n| `InMemoryFs` | Default. All data in memory. Zero host access. |\n| `OverlayFs` | Copy-on-write over a real directory. Reads from disk, writes stay in memory. |\n| `ReadWriteFs` | Passthrough to real filesystem. For trusted execution. |\n| `MountableFs` | Compose backends at different mount points. |\n\n### OverlayFs — Read real files, sandbox writes\n\n```rust\nuse rust_bash::{RustBashBuilder, OverlayFs};\nuse std::sync::Arc;\n\n// Reads from ./my_project on disk; writes stay in memory\nlet overlay = OverlayFs::new(\"./my_project\").unwrap();\nlet mut shell = RustBashBuilder::new()\n    .fs(Arc::new(overlay))\n    .cwd(\"/\")\n    .build()\n    .unwrap();\n\nlet result = shell.exec(\"cat /src/main.rs\").unwrap();    // reads from disk\nshell.exec(\"echo patched \u003e /src/main.rs\").unwrap();       // writes to memory only\n```\n\n### ReadWriteFs — Direct filesystem access\n\n```rust\nuse rust_bash::{RustBashBuilder, ReadWriteFs};\nuse std::sync::Arc;\n\n// Restricted to /tmp/sandbox (chroot-like)\nlet rwfs = ReadWriteFs::with_root(\"/tmp/sandbox\").unwrap();\nlet mut shell = RustBashBuilder::new()\n    .fs(Arc::new(rwfs))\n    .cwd(\"/\")\n    .build()\n    .unwrap();\n\nshell.exec(\"echo hello \u003e /output.txt\").unwrap();  // writes to /tmp/sandbox/output.txt\n```\n\n### MountableFs — Combine backends at mount points\n\n```rust\nuse rust_bash::{RustBashBuilder, InMemoryFs, MountableFs, OverlayFs};\nuse std::sync::Arc;\n\nlet mountable = MountableFs::new()\n    .mount(\"/\", Arc::new(InMemoryFs::new()))                                // in-memory root\n    .mount(\"/project\", Arc::new(OverlayFs::new(\"./myproject\").unwrap()))    // overlay on real project\n    .mount(\"/tmp\", Arc::new(InMemoryFs::new()));                            // separate temp space\n\nlet mut shell = RustBashBuilder::new()\n    .fs(Arc::new(mountable))\n    .cwd(\"/\")\n    .build()\n    .unwrap();\n\nshell.exec(\"cat /project/README.md\").unwrap();   // reads from disk\nshell.exec(\"echo scratch \u003e /tmp/work\").unwrap(); // writes to in-memory /tmp\n```\n\n## C FFI\n\nrust-bash can be used from any language with C FFI support (Python, Go, Ruby, etc.) via a shared library.\n\n### Build the shared library\n\n```bash\ncargo build --features ffi --release\n# Output: target/release/librust_bash.so (Linux), .dylib (macOS), .dll (Windows)\n# Header: include/rust_bash.h\n```\n\n### Minimal C example\n\n```c\n#include \"rust_bash.h\"\n#include \u003cstdio.h\u003e\n\nint main(void) {\n    struct RustBash *sb = rust_bash_create(NULL);\n    struct ExecResult *r = rust_bash_exec(sb, \"echo hello world\");\n    printf(\"%.*s\", r-\u003estdout_len, r-\u003estdout_ptr);\n    rust_bash_result_free(r);\n    rust_bash_free(sb);\n    return 0;\n}\n```\n\nFor complete Python and Go examples, see [`examples/ffi/`](examples/ffi/). For the full FFI guide, see the [FFI Usage recipe](docs/recipes/ffi-usage.md).\n\n## Public API (Rust)\n\n| Type | Description |\n|------|-------------|\n| `RustBashBuilder` | Builder for configuring and constructing a shell instance |\n| `RustBash` | The shell instance — call `.exec(script)` to run commands |\n| `ExecResult` | Returned by `exec()`: `stdout`, `stderr`, `exit_code` |\n| `ExecutionLimits` | Configurable resource bounds |\n| `NetworkPolicy` | URL allow-list and HTTP method restrictions for `curl` |\n| `VirtualCommand` | Trait for registering custom commands |\n| `CommandContext` | Passed to command implementations (fs, cwd, env, stdin, limits) |\n| `CommandResult` | Returned by command implementations |\n| `RustBashError` | Top-level error: `Parse`, `Execution`, `LimitExceeded`, `Network`, `Vfs`, `Timeout` |\n| `VfsError` | Filesystem errors: `NotFound`, `AlreadyExists`, `PermissionDenied`, etc. |\n| `Variable` | A shell variable with `value`, `exported`, `readonly` metadata |\n| `ShellOpts` | Shell option flags: `errexit`, `nounset`, `pipefail`, `xtrace` |\n| `ExecutionCounters` | Per-`exec()` resource usage counters |\n| `InterpreterState` | Full mutable shell state (advanced: direct inspection/manipulation) |\n| `ExecCallback` | Callback type for sub-command execution (`xargs`, `find -exec`) |\n| `InMemoryFs` | In-memory filesystem backend |\n| `OverlayFs` | Copy-on-write overlay backend |\n| `ReadWriteFs` | Real filesystem passthrough backend |\n| `MountableFs` | Composite backend with path-based mount delegation |\n| `VirtualFs` | Trait for filesystem backends |\n\n## Documentation\n\n- [Guidebook](docs/guidebook/) — architecture, design, and implementation details\n- [Recipes](docs/recipes/) — task-oriented guides for common use cases\n- [npm package README](packages/core/README.md) — TypeScript API reference\n- [AI Agent Guide](packages/core/AGENTS.md) — quick-start guide for AI agents consuming rust-bash\n\n## Roadmap\n\n- Planned: Embedded runtimes — SQLite, yq, Python, JavaScript\n- Planned: Platform features — cancellation, lazy files, AST transforms, fuzz testing\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshantanugoel%2Frust-bash","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshantanugoel%2Frust-bash","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshantanugoel%2Frust-bash/lists"}