{"id":51128378,"url":"https://github.com/microsoft/shell-use","last_synced_at":"2026-06-25T10:00:54.081Z","repository":{"id":221776001,"uuid":"748361025","full_name":"microsoft/shell-use","owner":"microsoft","description":"💻 Make the terminal / shell accessible for AI agents. Automate tasks with ease.","archived":false,"fork":false,"pushed_at":"2026-06-25T00:38:22.000Z","size":2408,"stargazers_count":187,"open_issues_count":3,"forks_count":16,"subscribers_count":5,"default_branch":"main","last_synced_at":"2026-06-25T02:11:42.790Z","etag":null,"topics":["ai-tools","automation","bash","cli","e2e-testing","fish","llm","powershell","pwsh","shell-use","terminal","testing","tui"],"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/microsoft.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":"SUPPORT.md","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":"2024-01-25T20:11:22.000Z","updated_at":"2026-06-25T00:38:26.000Z","dependencies_parsed_at":"2024-02-15T22:24:48.137Z","dependency_job_id":"e2138f71-a37e-425d-931a-5c485ac3418b","html_url":"https://github.com/microsoft/shell-use","commit_stats":null,"previous_names":["microsoft/tui-test","microsoft/shell-use"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/microsoft/shell-use","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2Fshell-use","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2Fshell-use/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2Fshell-use/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2Fshell-use/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/microsoft","download_url":"https://codeload.github.com/microsoft/shell-use/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2Fshell-use/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34769611,"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-06-25T02:00:05.521Z","response_time":101,"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":["ai-tools","automation","bash","cli","e2e-testing","fish","llm","powershell","pwsh","shell-use","terminal","testing","tui"],"created_at":"2026-06-25T10:00:53.392Z","updated_at":"2026-06-25T10:00:54.074Z","avatar_url":"https://github.com/microsoft.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# shell-use\n\n\u003e [!WARNING]\n\u003e **Work in progress.** `shell-use` is still being built out, so commands and behavior may change between releases \u0026 installation instructions may not yet work.\n\n`shell-use` is a rust powered cli for controlling, inspecting, testing, and recording shell sessions and terminal apps. It supports all standard terminal actions (send keys, mouse clicks) \u0026 user actions (screenshot, record sessions), \u0026 testing (matches screenshot, contains text). `shell-use` supports Windows, Linux, \u0026 macOS and it supports a wide range of shells (see [Supported shells](#supported-shells)).\n\n\n## Install\n\n### homebrew (macOS/linux)\n\n```sh\nbrew tap microsoft/shell-use https://github.com/microsoft/shell-use\nbrew install shell-use\n```\n\n### winget (windows)\n\n```sh\nwinget install Microsoft.ShellUse\n```\n\n### download from releases\n\nDownload the latest [release](https://github.com/microsoft/shell-use/releases).\n\n## Quick start\n\nRun a command and check the result:\n\n```sh\nshell-use open                  # start a shell session (auto-starts the daemon)\nshell-use submit \"echo hello\"   # type the command, press Enter\nshell-use wait command          # block until it finishes\nshell-use expect text \"hello\"   # assert it showed up\nshell-use expect exit-code 0    # assert it exited 0\nshell-use close\n```\n\nDrive a full-screen TUI the same way:\n\n```sh\nshell-use run vim file.txt\nshell-use wait idle             # let the screen settle\nshell-use press i\nshell-use type \"some text\"\nshell-use press Escape : w q Enter\nshell-use wait exit\n```\n\n## Built for agents\n\n`shell-use` is an AI native CLI. Point yours at the built-in docs and it can serve itself the rest:\n\n- `shell-use agent-context` prints versioned JSON for every command, flag, enum, default, and exit code. It is generated from the CLI, so it cannot drift from the real surface.\n- `shell-use usage` prints a one-screen cheatsheet.\n- `shell-use skill` prints the full workflow guide ([SKILL.md](SKILL.md)).\n\n### Skill quick start\n\n```sh\n# ~/.agents or ~/.claude instead to install it for every repo.\nmkdir -p .agents/skills/shell-use \u0026\u0026 shell-use skill \u003e .agents/skills/shell-use/SKILL.md   # copilot / codex\nmkdir -p .claude/skills/shell-use \u0026\u0026 shell-use skill \u003e .claude/skills/shell-use/SKILL.md   # copilot / claude\n```\n\nEach command returns a stable exit code (see [Exit codes](#exit-codes)), so an agent can tell an assertion failure from a missing session without scraping text.\n\n## Command reference\n\nGlobal flags: `--session \u003cname\u003e` (env `SHELL_USE_SESSION`, default `default`), `--json` for machine-readable output, and `--verbose`/`-v` to log PTY traffic (see [Debugging](#debugging)).\n\n### Session \u0026 lifecycle\n| Command | Description |\n| --- | --- |\n| `open [--shell S] [--cols N --rows N] [--cwd D] [--env K=V]` | Spawn a shell session. |\n| `run \u003cprogram\u003e [args...]` | Spawn a session running a program directly. |\n| `sessions` | List active sessions. |\n| `close [--all]` | Close the current session (or all). |\n| `daemon status` / `daemon stop` | Inspect / stop the daemon. |\n\n### Inspection\n| Command | Description |\n| --- | --- |\n| `state` | cwd, size, cursor, last command + exit code, text snapshot. |\n| `text [--full]` | Plain text of the viewport (or scrollback). |\n| `screenshot [-o file.svg] [--full]` | Terminal text to stdout, or a crisp full-color SVG image (svg-term-style window) to a file. |\n| `cells X Y [W H]` | Per-cell attributes (char, fg, bg, flags). |\n| `get command\\|output\\|exit-code\\|cwd\\|cursor\\|size` | Structured getters. |\n\n### Input\n| Command | Description |\n| --- | --- |\n| `type \"text\"` | Type literal text. |\n| `submit [\"text\"]` | Type then press the shell return key. |\n| `press \u003cKey...\u003e` | Named keys, e.g. `press Escape : w q Enter`, `press Ctrl+C`. |\n| `keys \"Control+a\"` | A single key combo. |\n| `mouse click X Y` / `mouse click --on-text \"OK\" [--clicks N]` | Click by coords or label. |\n| `mouse move\\|down\\|up\\|drag\\|scroll ...` | Full mouse control. |\n\n### PTY\n| Command | Description |\n| --- | --- |\n| `resize COLS ROWS` | Resize the PTY and emulator. |\n| `write \u003cdata\u003e` | Write raw bytes (no return key). |\n| `signal INT\\|TERM\\|KILL` / `kill` | Signal / kill the child. |\n\n### Wait\n| Command | Description |\n| --- | --- |\n| `wait text \"T\" [--regex --full --not --timeout MS]` | Until text is (not) visible. |\n| `wait idle` | Until the screen stops changing. |\n| `wait command` | Until the current command finishes. |\n| `wait exit` | Until the session exits. |\n\n### Expect (exit 0 = pass, 1 = fail)\n| Command | Description |\n| --- | --- |\n| `expect text \"T\" [--regex --full --no-strict --not --fg C --bg C --timeout MS]` | Visibility + optional color. |\n| `expect exit-code N` | Last command's exit code. |\n| `expect output \"T\" [--regex]` | Last command's captured output. |\n| `expect snapshot NAME [-u] [--include-colors]` | Compare against `__snapshots__/NAME.snap`. |\n\nColors accept ANSI-256 (`9`), hex (`#ff0000`), or rgb (`255,0,0`).\n\n### Screenshots\nScreenshots render a snapshot of the session in the current terminal by default, but can render an SVG using the `-o` output flag\n\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"full-color SVG screenshot of a TUI rendered by shell-use\" src=\"static/screen.svg\" width=\"400\"\u003e\n\u003c/p\u003e\n\n### Recording\nEvery session records automatically from the moment it opens, in the standard\n[asciinema v2](https://docs.asciinema.org/manual/asciicast/v2/) cast format.\n\n| Command | Description |\n| --- | --- |\n| `get-recording [session]` | Print the session's recording (cast) to stdout. |\n\n```sh\nshell-use get-recording \u003e demo.cast   # capture the current session's recording\nasciinema play demo.cast              # replay it\nagg demo.cast demo.gif                # render a GIF\n```\n\n### Live monitor\nWatch a live session in a second terminal while an agent drives it. Both share\nthe same daemon. `monitor` takes over an alternate screen and streams the\nsession in full color at ~20fps; press `q`, `Esc`, or `Ctrl-C` to detach.\n\nhttps://github.com/user-attachments/assets/741c985f-7861-41c5-9ceb-0f82f705b43f\n\n| Command | Description |\n| --- | --- |\n| `monitor` | Attach a live, full-color framed view of the session (`--session` selects which). |\n\n```sh\nshell-use --session work monitor   # watch the 'work' session live\n```\n\nIt needs an interactive terminal (exit `2` otherwise) and an existing session\n(exit `3` if none). The view reads only the shared screen state, so watching\nnever blocks the commands the agent is running, and resizing the window just\nre-fits the frame.\n\n### Agents\n| Command | Description |\n| --- | --- |\n| `usage` | Compact command cheatsheet. |\n| `agent-context` | Versioned JSON describing every command, flag, enum, default, and the exit-code taxonomy (generated from the CLI, so it can't drift). |\n| `skill` | Long-form workflow guide ([SKILL.md](SKILL.md)). |\n\n### Exit codes\nEvery command returns a stable exit code so an agent can branch on the failure class without parsing text:\n\n| Code | Meaning |\n| --- | --- |\n| `0` | success |\n| `1` | assertion or wait condition not met (`expect`/`wait`) |\n| `2` | usage / invalid argument |\n| `3` | no active session (run `open`/`run` first) |\n| `4` | daemon or IPC error |\n| `5` | internal error |\n\nWith `--json`, failures also carry a `\"kind\"` field (`assertion`/`usage`/`no_session`/`internal`).\n\n## Supported shells\n\n- bash\n- zsh\n- fish\n- PowerShell (`powershell` and `pwsh`)\n- xonsh\n- elvish\n- nushell\n- cmd\n\n## Comparison\n\n`shell-use` shares its shape with two related tools, both linked in the table:\n\n| | shell-use | [tui-use](https://github.com/onesuper/tui-use) | [terminal-use](https://github.com/flipbit03/terminal-use) |\n| --- | --- | --- | --- |\n| Language | Rust | TypeScript/Node | Rust |\n| Emulator | alacritty | xterm (headless) | alacritty |\n| Primary target | shells **and** TUI apps | REPLs / debuggers / TUI apps | TUI apps |\n| Shell command tracking ([OSC 133](https://gitlab.freedesktop.org/Per_Bothner/specifications/blob/master/proposals/semantic-prompts.md)/633) | ✅ command boundaries, exit codes, cwd | ❌ | ❌ |\n| Testing / snapshots | ✅ `expect` text / output / exit-code / snapshot | ❌ | ❌ |\n| Color \u0026 per-cell attributes | ✅ fg/bg, ANSI-256/hex/rgb, `cells` | ❌ plain text (+ highlights) | via PNG |\n| Image screenshots | ✅ SVG | ❌ | ✅ PNG |\n| Built-in recording | ✅ always-on asciinema cast + GIF | ❌ | ❌ |\n| Live monitor view | ✅ | ❌ | ✅ |\n| Stable exit-code taxonomy for agents | ✅ | ❌ | ❌ |\n| Runtime | native | Node.js | native |\n| Platforms | Windows + Unix | Windows + Unix | Linux / macOS |\n\nThe difference is testing: `shell-use` tracks command boundaries and exit codes across every supported shell, then adds assertions, snapshots, color checks, and an always-on recording on top of the usual drive-and-read loop. It ships as one self-contained native binary with no runtime to install, where a Node tool like tui-use pulls in a full Node.js runtime and its native modules.\n\n## Debugging\n\nBy default the daemon writes no log. Start it with `--verbose` to record every byte read from and written to the PTY, plus lifecycle events, to `~/.shell-use/\u003csession\u003e.log`:\n\n## Contributing\n\nThis project welcomes contributions and suggestions. Most contributions require you to agree to a\nContributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us\nthe rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.\n\nWhen you submit a pull request, a CLA bot will automatically determine whether you need to provide\na CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions\nprovided by the bot. You will only need to do this once across all repos using our CLA.\n\nThis project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).\nFor more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or\ncontact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.\n\n## Trademarks\n\nThis project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft\ntrademarks or logos is subject to and must follow\n[Microsoft's Trademark \u0026 Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general).\nUse of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.\nAny use of third-party trademarks or logos are subject to those third-party's policies.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicrosoft%2Fshell-use","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmicrosoft%2Fshell-use","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicrosoft%2Fshell-use/lists"}