---
title: Quickstart
description: Install Forge in Omarchy, create a plugin, check it, preview it safely, and try it in the shell.
---

# Quickstart



This guide takes you from an Omarchy terminal to a running example plugin.
Forge runs on the Linux machine where Omarchy is installed. If your everyday
computer is Windows or macOS, enter the terminal **inside Omarchy** before
continuing.

## Prerequisites [#prerequisites]

* Omarchy 4 with shell plugin support.
* A terminal open inside Omarchy.
* Git and `curl`, used for installation and local plugin development.

You do not need Go or `sudo` to use the published Forge release.

## Install Forge [#install-forge]

The short installer detects whether the machine uses an AMD/Intel or ARM
processor, resolves the latest published release, verifies its checksum, and
installs Forge for your user:

```bash
curl -fsSL https://www.omarchyforge.com/install.sh | bash
```

Run the same command later to check for and install a newer release. It exits
without downloading an archive when the installed version is already current.
Updates are always explicit; Forge never checks or updates in the background.

To inspect the script before running it:

```bash
curl -fsSLo /tmp/omaforge-install.sh https://www.omarchyforge.com/install.sh
less /tmp/omaforge-install.sh
bash /tmp/omaforge-install.sh
rm -f /tmp/omaforge-install.sh
```

To install an exact release instead of the latest:

```bash
curl -fsSL https://www.omarchyforge.com/install.sh | bash -s -- --version v0.4.0
```

<details>
  <summary>
    Fully manual v0.4.0 installation
  </summary>

  This expanded form performs the same architecture detection, checksum
  verification, user-only installation, and temporary cleanup without relying on
  the hosted script:

  ```bash
  (
    set -eu
    version="0.4.0"
    case "$(uname -m)" in
      x86_64) arch="amd64" ;;
      aarch64|arm64) arch="arm64" ;;
      *) echo "Unsupported CPU: $(uname -m)" >&2; exit 1 ;;
    esac
    install_tmp="$(mktemp -d)"
    trap 'rm -rf -- "$install_tmp"' EXIT
    cd "$install_tmp"
    curl -fLO "https://github.com/omarchy-forge/forge/releases/download/v${version}/omaforge_${version}_linux_${arch}.tar.gz"
    curl -fLO "https://github.com/omarchy-forge/forge/releases/download/v${version}/checksums.txt"
    sha256sum --ignore-missing --check checksums.txt
    tar -xzf "omaforge_${version}_linux_${arch}.tar.gz"
    install -Dm755 omaforge "$HOME/.local/bin/omaforge"
    "$HOME/.local/bin/omaforge" version
  )
  cd "$HOME"
  ```
</details>

Both paths change only `~/.local/bin/omaforge`, remove temporary downloads, and
leave the terminal in its original directory. If a new terminal says that
`omaforge` is not found, run it as `$HOME/.local/bin/omaforge` or add
`~/.local/bin` to your `PATH`.

## Create a bar widget [#create-a-bar-widget]

For the normal scaffold:

```bash
cd "$HOME"
omaforge init project-pulse --git
```

Or, for the agent-ready scaffold instead:

```bash
cd "$HOME"
omaforge init project-pulse --git --agent-ready
```

Forge asks for the remaining information. Use a unique reverse-domain plugin ID
such as `dev.yourname.project-pulse`. You can press Enter to accept appropriate
defaults.

Forge refuses dangerous targets, symlinked output trees, and unexpected files.
Use `--dry-run` to preview the complete write plan without creating anything.

The optional `--agent-ready` path creates a structured `FORGE_SPEC.md` and
project-scoped `AGENTS.md` without contacting or launching an AI service.
Complete the specification, change its status from `Draft` to
`Ready for implementation`, commit that rollback point, and follow the
[agent-ready workflow](/docs/templates#agent-ready-projects) before executing
any agent-written QML.

## Check and validate [#check-and-validate]

```bash
cd "$HOME/project-pulse"
omaforge check .
omaforge doctor .
omarchy plugin validate .
```

`check` inspects project structure without executing plugin QML. `doctor`
performs read-only local environment probes. The final command runs Omarchy's
official validator; Forge complements it rather than replacing it.

## Preview safely [#preview-safely]

Review the generated QML and local commands before acknowledging that you trust
the code. Then run it in Forge's isolated temporary runtime:

```bash
omaforge dev . --trust-plugin-code --state ready
```

Try empty and error states, or keep the preview refreshed while editing:

```bash
omaforge dev . --trust-plugin-code --state empty
omaforge dev . --trust-plugin-code --state error
omaforge dev . --trust-plugin-code --state ready --watch
```

Stop watch mode with `Ctrl-C`. These commands do not install the plugin, change
Omarchy configuration, or connect to the live shell.

## Try the plugin [#try-the-plugin]

Review the generated source before enabling it; plugins run unsandboxed inside
the long-lived Omarchy Shell process.

```bash
omarchy plugin add "$PWD" --enable
./demo/run empty
```

When testing is complete, remove it. Replace the example ID with the exact value
entered during creation:

```bash
omarchy plugin remove dev.yourname.project-pulse
```

## Capture a preview [#capture-a-preview]

Forge can capture only the plugin-declared panel content—never the desktop:

```bash
omaforge screenshot . \
  --trust-plugin-code \
  --state ready \
  --output assets/preview.png
```

Forge refuses to overwrite an existing image.

## What to do next [#what-to-do-next]

* Read the [command reference](/docs/commands) for every flag and output format.
* Learn the generated structure in [plugin anatomy](/docs/plugin-anatomy).
* Add automated checks using the generated GitHub Actions workflow.
* Edit the QML, rerun `omaforge check .`, and preview each state before enabling
  the plugin again.

## Build Forge from source [#build-forge-from-source]

This path is only for contributors working on Forge itself. It requires Go 1.23
or newer:

```bash
git clone https://github.com/omarchy-forge/forge.git
cd forge
go build -o ./tmp/omaforge ./cmd/omaforge
./tmp/omaforge version
```


---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)