Installation and first task

Requirements

The current pinned Nix packages support Linux on x86-64 and ARM64, and macOS on Apple silicon. Although the flake declares an Intel macOS output, its current nixpkgs pin no longer supports that platform. You need:

• Nix with flakes enabled.
• A terminal and a project directory.
• A supported provider account, API key, or compatible model endpoint.
• Git when using managed worktrees.

You do not need to install GHC to use the packaged agent. Its optional persistent GHCi tool requires a separate GHC environment.

Try without installing

Run the agent from the directory you want it to work in:

nix run --accept-flake-config github:digitallyinduced/haskell-agent

--accept-flake-config accepts the repository's declared binary-cache settings. The first invocation may download the runtime and dependencies.

Install in your Nix profile

nix profile add --accept-flake-config github:digitallyinduced/haskell-agent
agent-cli --version

Verify the bundled PostgreSQL runtime, which provides local durable storage:

agent-cli storage start
agent-cli storage doctor
agent-cli storage stop

Run this check before opening agent sessions; do not stop storage while other sessions are using it.

1. Open a project

The remaining steps use the installed agent-cli. Replace the example path with an existing project you are allowed to inspect. In a Git project, check git status first so you can distinguish existing work from new changes.

agent-cli --cwd /absolute/path/to/project

Without a profile installation, use the same options after the flake separator:

nix run --accept-flake-config github:digitallyinduced/haskell-agent -- --cwd /absolute/path/to/project

Expected result: an interactive session opens. Commands beginning with / below belong in its prompt, not in your shell.

2. Connect a model

Open /login and connect a supported provider account. Then use /model to select a model available to that account. Provider-specific credentials and billing are explained in Authentication.

/login
/model
/session-info

Enter these commands one at a time, completing each interface before continuing. Expected result:/session-info reports the active model and session details. Never paste an API key into the ordinary conversation.

3. Inspect before editing

Submit this prompt:

Read the project instructions and explain the directory structure.
Identify the normal test command. Do not modify files.

The agent streams its response and displays tool activity. Review any approval request before permitting the proposed action. Read the actual operation, not just the explanation; deny a request that does not fit your task.

Expected result: a summary naming relevant files and a test command supported by the repository, or an explicit explanation that the command could not be established. Asking for no edits is an instruction to the model, not an operating-system read-only boundary.

If the repository has an AGENTS.md, its guidance is discovered by default. If it does not, /init can ask the agent to create one. That is an optional write operation: review the generated guide before relying on it. See project instructions and planning.

4. Make a small change

A documentation improvement is a useful first task because its scope is easy to inspect. After confirming the test command above, submit:

Update README.md with a short section explaining how to run the existing tests.
Use only commands supported by this repository. Do not change application code.
Run the documentation checks if the project defines them, and report what you ran.
Do not commit or push.

If your project uses a different documentation file, substitute that path. Expected result: a focused documentation change, a summary of the evidence for each command, and check results or a clear statement that checks could not run. For a larger change, start with /plan and approve the proposal before implementation.

5. Review and correct the result

/diff

Inspect every changed file. The diff can include work that existed before the session, so compare it with your initial git status. Ask for a correction if the change exceeds the agreed scope:

Keep the README test instructions, but remove changes unrelated to that task.
Preserve all edits that were already present before this session.
Explain the remaining diff and any checks you could not run.

Review the resulting diff again. Neither a successful response nor a generated review proves the change is correct. Commit only after your own review. Conversation commands such as /clear do not undo filesystem changes.

6. Leave and return

Give this session a recognizable name, then leave it:

/rename First project walkthrough
/quit

Start agent-cli again and enter /resume to choose the saved conversation. Expected result: you can continue the earlier task without copying its prompts into a new session. Session persistence does not back up your project files. See Sessions for export and recovery options.

If a step does not work

• The program does not start: check Nix installation and the storage diagnostics above before changing provider settings.
• A model request is rejected: inspect /login, /model, and /usage; account access and billing vary by provider.
• A tool is blocked: read the approval or sandbox explanation. Do not disable protections merely to complete the tutorial.
• The agent selected the wrong files: stop requesting edits, clarify the project path and scope, and review the diff before continuing.

See Troubleshooting for diagnostics and Approvals and sandboxing for execution boundaries.

Run one task and exit

agent-cli --cwd /absolute/path/to/project \
  -p "Explain this project's entry points without modifying files."

Add --save-session if you want a one-shot run persisted as a session. Non-interactive runs cannot rely on an interactive approval prompt; see approvals before automating writes.

Update

nix profile upgrade --refresh --accept-flake-config haskell-agent

nix profile add does not upgrade an existing profile entry. If the entry has a different name, inspect nix profile list and use that name for the upgrade.

Apple silicon Macs running macOS 14 or newer also have a standalone release archive. See the repository's release installation instructions for that separate distribution.