> ## Documentation Index
> Fetch the complete documentation index at: https://altostrat.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Local shell and code tools
> Run commands on the Studio workstation, keep an interactive local terminal, and let Copilot inspect or change a grounded repository with structured code tools.
Studio distinguishes a remote device terminal from work performed on the local workstation:
* A **host terminal** connects to an inventory host over SSH, Telnet, or serial.
* A **local shell command** runs through a real shell selected for the workstation.
* An **interactive local terminal** stays open when a command needs persistent state, visibility, or input.
* **Code tools** inspect and change files inside a grounded repository with operations designed for source work.
Always confirm which boundary a command targets. `show interfaces` in a router terminal and `git status` in a local repository can appear in the same conversation but affect different systems.
## Choose the execution path
| Need | Preferred path |
| --------------------------------------------------------------- | ---------------------------------------------------------------------- |
| Inspect or change a managed device | Open its tracked host terminal. |
| Run one local command, test, formatter, build, or Git operation | Local shell command. |
| Maintain an interactive process or visible prompt | Interactive local terminal. |
| Locate, read, diff, or edit repository files | Structured Code tools, with local shell for the test or build. |
| Inspect OS configuration without clicking through UI | Native inspection tools when available. |
| Operate a graphical application | Direct CLI or structured tool first; Computer Use only when necessary. |
This routing keeps repository reads precise and prevents a local shell command from being mistaken for a command on the active network device.
## Local shell commands
For one-shot work, Copilot uses the local shell tool. The selected shell depends on the workstation:
* On macOS, Studio uses an available `zsh` or `bash` path with the appropriate shell syntax.
* On Windows, Studio selects from PowerShell 7, Windows PowerShell, Git Bash, and `cmd` according to availability.
The command can run in a chosen working directory. Long-running commands can continue as background jobs; Studio can read new output, report exit state, or terminate the job.
Examples:
* “Run the tests for this repository and summarize only the failures.”
* “Show the Git status and diff without changing anything.”
* “Start the development server in the background and tell me when it is ready.”
* “Stop the background job that is still listening on the test port.”
Local shell execution is approval-gated according to the current mode and session approval state. Autopilot can remove the per-call prompt, so keep it off when the working directory or command is not already verified.
## Interactive local terminal
Use the local Terminal surface when you need to watch output, answer a prompt, maintain shell state, or interact with a process directly. Open it from the Terminal launcher or ask Studio to show the local terminal.
By default, Copilot can prepare a local terminal in the background and return command details in the conversation. Ask it to show the panel when you need to see or control the session.
On Windows, the persistent Terminal can use Studio's portable built-in shell. It supports common file, text, network, pipeline, redirection, history, and completion operations, but it is not a complete PowerShell or POSIX scripting environment. Use a real local shell command for a script, build tool, Git workflow, or platform-specific command.
## Ground a repository
When your prompt clearly refers to a local repository or codebase, Studio can activate the Code domain for that workspace. State the repository path or attach the relevant workspace context when more than one repository is plausible.
The structured workflow is:
1. Map the repository at a useful level.
2. Locate paths with file matching and symbols or text with code search.
3. Read only the relevant ranges.
4. Inspect the repository diff before and after a change.
5. Use the local shell for tests, builds, formatters, and Git operations.
This is more reliable than reconstructing every file operation through a shell pipeline and keeps large repositories from flooding the model context.
## Code tabs and source files
Studio can open generated code or configuration in a Monaco editor tab. A code tab is useful for review, syntax highlighting, comparison, and iteration. It is not automatically the source file in a repository.
Before asking Studio to edit code, make the destination explicit:
* **Repository edit** — change the named file in the grounded workspace and verify the diff.
* **Generated snippet** — create or update a Studio code artifact without touching the filesystem.
* **Remote file** — edit the named path through the host's SFTP connection.
Confusing these destinations is a common cause of “the code looks changed, but the application did not change.”
## Review local changes safely
Before approving a local write or command:
1. Confirm the workstation, repository root, and working directory.
2. Inspect existing uncommitted and untracked work.
3. Read the exact command or patch and its targets.
4. Keep unrelated user changes intact.
5. Run the narrowest relevant validation.
6. Inspect the final diff and generated files.
7. Do not commit, push, publish, install software, or delete work unless that action is part of the stated task.
A local command can read workstation files, start processes, reach the network, change source, or delete data with the current user's permissions. “Local” describes where it runs, not how safe it is.
## Secrets and output
* Keep tokens and passwords in Key Chain or the platform's approved secret path.
* Do not put a secret in a command argument when it will appear in the transcript, process list, shell history, or telemetry.
* Treat build logs and test output as possible model context once returned to the conversation.
* Stop background jobs and local servers when their task ends.
* Verify generated configuration against the target version and environment before deployment.
## Troubleshooting
| Symptom | What to check |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| Command ran in the wrong folder | State the absolute working directory and verify it before retrying. |
| Studio used a shell instead of Code tools | Attach or name the repository and ask it to inspect with structured Code tools first. |
| A generated code tab did not change the app | Confirm whether the tab was an artifact or a saved repository file. |
| Windows syntax fails | Check which real shell Studio selected; PowerShell, Git Bash, and `cmd` use different syntax. |
| A command is still running | Ask for background-job status, read the latest output, or terminate the named job. |
| Code tools are missing | Check organization and channel tool policy, then discover or enable the Code domain if permitted. |
## Related
Connect to tracked devices and review staged remote commands and replays.
Distinguish generated artifacts, remote SFTP files, replays, and saved work.
Prefer structured and command-line paths before graphical control.
Understand local execution, secrets, approvals, and recordings.