> ## Documentation Index
> Fetch the complete documentation index at: https://docs.luminy.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Shell and Git Tools: Run Commands With the Luminy Agent

> Luminy's agent runs terminal commands and git operations in your project, streaming live output into the chat with per-command permission controls.

The agent can run shell commands and git operations as part of its workflow — not just read and write files, but actually execute code, run tests, install packages, and manage your repository. Commands run in a live terminal session so output streams directly into the chat in real time, the same way you would see it in a terminal emulator.

## Shell execution

When the agent runs a command, it opens a terminal session in your project directory and streams the output back in real time. After the command finishes, the output appears in the chat as a collapsible **console badge** showing the command and its exit status.

**Common use cases:**

* Running your test suite after implementing a change
* Installing dependencies (`npm install`, `pip install -r requirements.txt`)
* Building the project (`cargo build`, `npm run build`)
* Starting a dev server to verify something works
* Running linters or type-checkers

**Example flow:** you ask the agent to add a new API endpoint. It reads the relevant files, writes the implementation, then runs `npm test` to verify nothing is broken. If tests fail, it reads the error output and iterates — all without leaving the chat.

<Tip>
  Ask the agent to **run your test suite after making changes**. Because it can read the failure output and immediately fix the cause, it often resolves test failures in the same run without you having to paste error messages.
</Tip>

### Long-running commands

The default command timeout is 30 seconds (up to a maximum of 5 minutes for operations you expect to take longer). If a command is still running when the timeout expires, it continues in the background as a named console session. The agent can resume reading its output later or stop it — you can also see running sessions in the chat and cancel them from there.

## Git operations

The agent can run any git command in your project directory. Git output is shown in the chat the same way as any other shell command, so you can follow every step.

**Operations the agent commonly uses:**

| Command                    | Purpose                             |
| -------------------------- | ----------------------------------- |
| `git status`               | Check what has changed              |
| `git diff`                 | Inspect unstaged and staged changes |
| `git add`                  | Stage files for commit              |
| `git commit -m "…"`        | Commit changes with a message       |
| `git log --oneline`        | Browse recent history               |
| `git checkout -b <branch>` | Create and switch to a new branch   |
| `git stash`                | Temporarily shelve changes          |

The agent also has a dedicated `get_git_diff` tool that returns staged changes, unstaged changes, and untracked files in a single call — useful when it wants a quick snapshot of what has changed before deciding what to do next.

<Tip>
  After the agent completes a task, ask it to **commit the changes with a descriptive message**. This gives you a clean checkpoint you can revert to and makes the history easier to follow.
</Tip>

<Warning>
  **The agent can modify your git history.** Commands like `git reset --hard`, `git rebase`, and `git push --force` are within its reach. If you are working on a shared branch or a production repository, enable permission mode (see below) so you can review each command before it runs.
</Warning>

## Permission controls

Shell commands are the most powerful — and most consequential — tools the agent can call. Luminy gives you granular control over when they run.

<Tabs>
  <Tab title="Require approval">
    The agent pauses before each shell command and shows you the exact command it wants to run. You can approve it, deny it, or edit it before execution. This is the safest mode.

    **Enable:** Settings → Permissions → Shell commands → **Require approval**
  </Tab>

  <Tab title="Always allow">
    The agent runs shell commands without asking. Choose this if you trust the agent's judgment for the current session and want it to iterate quickly.

    **Enable:** Settings → Permissions → Shell commands → **Always allow**
  </Tab>

  <Tab title="Always deny">
    Shell commands are blocked entirely. The agent can still read, write, and edit files but cannot execute anything.

    **Enable:** Settings → Permissions → Shell commands → **Always deny**
  </Tab>
</Tabs>

You can also grant or deny permission for an individual command inline when the agent asks — without changing the global setting.

See [Permissions](/configuration/permissions) for a complete reference on all permission modes and how they interact.

<Warning>
  **Be cautious with destructive commands.** Instructions like `rm -rf`, `git reset --hard`, `git push --force`, or `DROP TABLE` can cause irreversible data loss. If you are unsure, enable **Require approval** so you can read the command before it runs.
</Warning>