Skip to content

INSTALL.md

Latest commit

 

History

History
260 lines (171 loc) · 9.71 KB

INSTALL.md

File metadata and controls

260 lines (171 loc) · 9.71 KB
Raw

Install and set up Autter

Autter is an open source Git extension that records which lines were written by AI agents and links those lines to the agent, model, and prompts behind them. You can use it entirely on your own machine, or connect it to autter.dev for organization-wide dashboards and collaboration.

Connecting to the platform is optional. The CLI's local authorship tracking, blame, and stats features do not require an Autter account.

1. Install the CLI

macOS, Linux, and Windows with WSL

Run:

curl -fsSL https://api.autter.dev/install.sh | bash

Windows (PowerShell, Command Prompt, or Git Bash)

Run:

powershell -NoProfile -ExecutionPolicy Bypass -Command "iex (irm https://api.autter.dev/install.ps1)"

npm (any platform, Node.js 18+)

npm install -g @autter/cli
autter onboard

The npm package is a thin bootstrapper that downloads the same release binary into ~/.autter/bin and verifies its checksum against the GitHub release, then exposes autter through the npm global bin directory. Hooks, the background service, and autter upgrade work identically to the script installs. One-shot bootstrap without a global install: npx @autter/cli onboard.

Git Bash is not WSL. The bash installer only runs on macOS, Linux, and WSL; in Git Bash it exits with instructions instead of installing. Use the Windows command above (it also works from Git Bash), and install Autter in the environment where your coding agents run — agents inside WSL need the WSL install.

Signed in to the Autter dashboard? Settings → CLI setup generates a single-use command that runs this same installer and signs the machine in automatically.

The installer downloads Autter into ~/.autter/bin and adds it to your user PATH. IDE/agent hooks, global git capture settings, and the background service are applied during autter onboard (with consent) or with autter install --system. On macOS, Linux, and WSL the script starts onboarding when the shell is interactive. Automated or non-interactive installs can finish onboarding later with autter onboard.

System requirements

  • git 2.22 or newer (required)
  • Linux: glibc 2.35 or newer (Ubuntu 22.04+, Debian 12+, Fedora 36+). Ubuntu 20.04 and older WSL2 distros are not supported natively — use a newer WSL distro or run inside an ubuntu:22.04 Docker container
  • macOS: 11 (Big Sur) or newer
  • Windows: 10 or newer
  • npm path: Node.js 18+

On macOS, Linux, and WSL, make autter available in the terminal you already have open (the installer prints this command at the end too):

source "$HOME/.autter/env"   # fish: source "$HOME/.autter/env.fish"

New terminals pick it up automatically. Restart your IDE (not just its terminal tab) so IDE terminals and coding agents see it too. Then verify the CLI is available:

autter --version
autter doctor   # v1.7.1+ — focused setup validation (exits 1 on failure)
autter debug    # full support dump (always exits 0)

autter doctor runs end-to-end checks (git proxy, hooks, checkpoint round-trip). On v1.6.9 and earlier, use autter debug instead.

You do not need to configure each repository separately. Continue using Git, your IDE, and your coding agents as usual.

Using Nix? See the Nix installation guide for NixOS, nix-darwin, and Home Manager options.

2. Choose how to use Autter

Run the guided setup at any time:

autter onboard

The setup offers two modes.

Connect to the Autter platform

Connecting this machine makes the local attribution useful beyond one laptop or repository. It lets you:

  • search and inspect the prompt and model behind an AI-generated change;
  • see AI and human authorship across repositories, contributors, and teams;
  • understand which agents, models, and workflows are effective;
  • follow AI-generated code through review and into production; and
  • keep organization-wide audit history and usage trends in one place.

Local Git notes remain available when connected. Prompt and usage data also syncs to your organization's Autter environment. See Data Privacy for exactly what is stored in each mode.

The simplest login method is the guided browser flow:

autter onboard

Choose to connect when prompted. Autter opens a browser, shows a one-time code, and waits for you to authorize the device. To select connected mode without the initial question, run:

autter onboard --connect

To sign in again later (for example after a session expires), run:

autter login

If the browser-based flow does not work, use a Personal Access Token (PAT):

  1. Sign in to the Autter web app.

  2. Open the organization you want to connect.

  3. Go to Org Settings → Access Tokens.

  4. Create and copy a Personal Access Token.

  5. Add the token to the CLI:

    autter login --token <paste-your-token>

Treat a PAT like a password: do not commit it, paste it into chat, or include it in shell scripts. After either login method, confirm the active identity and organization:

autter whoami

If you belong to more than one organization, Autter uses the repository's Git remote to route connected data to the organization that owns it, with your default organization as the fallback.

Use Autter locally without logging in

An account is not required. Choose local-only during autter onboard, or select it directly:

autter onboard --local

In local-only mode:

  • line-level attribution is stored in local Git notes under refs/notes/ai;
  • prompts remain in local storage on your machine;
  • local commands such as autter blame and autter stats continue to work; and
  • no code, prompts, or agent usage data is uploaded to the Autter platform.

Open source error and exception telemetry is enabled by default. If you want Autter to send no telemetry at all, turn it off:

autter config set telemetry_oss off

You can connect later without reinstalling:

autter onboard --connect

To disconnect an existing installation and return to local-only mode:

autter logout
autter onboard --local --force

3. Use Autter

There is no new commit workflow to learn. Ask your supported agent to edit code, review the changes, and commit normally:

git add .
git commit -m "Describe the change"

Autter attaches authorship metadata to the commit automatically. Useful commands include:

# See line-by-line human and AI authorship
autter blame path/to/file

# Summarize authorship over a commit or range
autter stats
autter stats <start-sha>..<end-sha>

# Check the current platform login
autter whoami

# Re-run agent/editor integration setup
autter install-hooks

# Upgrade to the newest release
autter upgrade

Run autter help for the full command list.

Open source, extensible, and local-first

The CLI and the Autter authorship standard are open source. The platform is an optional collaboration layer, not a requirement for attribution. You can build and run your own solution on the standard, keep it local, or connect Autter to the tools your organization already uses.

Community contributions are welcome, including:

  • support for new coding agents and checkpoint formats;
  • editor and IDE plugins that display authorship and prompt context;
  • CI integrations and workflows;
  • storage, reporting, and self-hosting integrations; and
  • fixes and improvements to the CLI and open standard.

Start with the contribution guide, read the agent integration guide, or open a pull request. Existing community editor plugins are listed in the main README.

Troubleshooting

autter: command not found

In an already-open terminal on macOS, Linux, or WSL, load the PATH entry directly:

source "$HOME/.autter/env"   # fish: source "$HOME/.autter/env.fish"

New terminals load it automatically via your shell configuration. If the command is still not found in a fresh terminal, shell detection could not update your profile — add this line to your shell configuration (for fish, use the env.fish variant) and restart the shell:

. "$HOME/.autter/env"

An agent or editor installed after Autter is not detected

Re-run integration setup:

autter install-hooks

Browser onboarding fails

Use the PAT fallback described above:

autter login --token <paste-your-token>
autter whoami

Change the original onboarding choice

autter onboard --force

Attribution checks fail (autter doctor / autter debug)

autter doctor prints a fix: line with a likely cause and next command for each failure. Common cases:

  1. Checkpoints not persisting (timeout waiting for working-log entries):
    autter daemon status, then autter daemon restart, then autter doctor.
  2. Trace2 config / event capture failed:
    autter install, then autter doctor. Attribution depends on the git proxy and trace2 settings.
  3. Commit succeeded but blame lines are all untracked / wrong class:
    post-commit notes did not land — usually the same as (2). Run autter install and ensure commits go through the Autter-managed git.
  4. Still stuck: run autter debug and review (or share) its attribution self-check section, including the leftover self-check repo path if one was kept for inspection.

When autter diff / blame / show report missing authorship on real commits, the same sequence applies: hooks (install-hooks) → install → doctor.

For additional diagnostics, run autter debug and review its output before including it in an issue.