AI Agent

Pointy includes an embedded LLM agent that lets you create and edit steps, projects, and source files from plain-language descriptions. The agent works directly on the Git-backed user repository, operates inside isolated Git worktrees, edits only allowlisted paths, and puts every change through a review-and-apply workflow before it reaches the live repository. The result is an ordinary version-controlled commit: inspectable, shareable, and reversible like any other change.

The agent panel is available from every page. Administrators configure the runner through the [agent] section of the backend configuration; see Instance Admin Guide.

Opening the agent panel

You don't need to know the exact Nix syntax. Use the fixed Agent button near the bottom-right corner of any Pointy page to open the panel. Minimize and Close both hide it without ending the current chat; use the same fixed button to reopen it. Maximize expands the panel to the browser edges, and Restore returns it to its floating size.

The panel preserves your selected chat and typed-but-unsent prompt while it is hidden or resized.

Managing chats

New chat

Click New chat in the sidebar to create a fresh agent session. Each new chat gets its own isolated Git worktree branched from the current tip of the configured target branch.

Naming a chat

By default a chat shows the first few words of your first prompt. To give it a name, click the pencil icon in the chat title bar, type the name (up to 80 characters), and press Enter or click Save. Press Escape to cancel.

Chat sidebar

The sidebar lists your chats in two groups:

• Active chats appear at the top, newest first. Click a row to open it.
• Archived chats are hidden by default. Click Show archived (N) at the bottom of the sidebar to reveal them.

Each row shows the chat name, its current status, and a changes pill when the agent has committed changes that have not yet been applied or discarded.

Sending a prompt

Describe what you want in plain language. The agent understands the repository structure and works with the same file formats the UI uses. Type your request in the text area at the bottom of the chat and click Send, or press Ctrl+Enter (or Cmd+Enter on macOS). The agent starts immediately and streams its reply into the chat as Markdown. A blinking cursor shows that the reply is still in progress.

While a turn is running, the prompt input and Send button are disabled. The status label reads Working during execution, then Done when complete, or Failed if the runner exits with a non-zero code.

How the agent works

Isolated Git worktrees

Every chat session owns a dedicated git worktree that starts from the configured target branch. The agent runs inside this worktree under a sandbox (sbox by default), so it cannot reach backend credentials, SSH keys, or the host filesystem beyond what the administrator explicitly binds.

Target-branch refresh before each turn

Before each turn, Pointy fetches the latest state of the target branch. A worktree with no local commits simply fast-forwards to the new tip. When the agent has already made commits, Pointy attempts to merge the target branch into the session branch instead. A clean merge lets the agent continue from the merged commit. If the merge conflicts, Pointy logs a warning and the agent continues from the previous base commit. You can resolve the situation in the chat afterward.

Path allowlist

The agent can edit files, but only inside these patterns:

• projects/<numeric-id>.nix
• steps/<numeric-id>.nix
• srcFiles/<numeric-step-id>/<relative-path>

After each turn, Pointy automatically commits only files that match these patterns. Other changed paths are reported in the turn log, remain outside the changeset, and are never applied to the target branch.

Reviewing and applying changes

Changeset review

When the agent makes commits inside its worktree, a Changeset box appears in the chat showing the diff between the session branch and the base commit. The changeset has a status:

• Proposed: the changes are ready for review and can be applied or discarded.
• Needs review: the changes could not be prepared cleanly (for example, a merge conflict against the current target branch). You can continue the conversation to resolve the conflict, or discard the changeset.

Applied and discarded changesets remain in the chat history as lifecycle markers.

Apply (two-stage with stale/conflict protection)

Clicking Apply changes on a proposed changeset triggers a two-stage process:

1. Prepare: Pointy creates a temporary apply worktree at the current target-branch tip and squashes the agent's commits onto it. A conflict changes the changeset to Needs review instead of touching the target branch.
2. Confirm and push: Pointy verifies that the target branch and prepared candidate are still the exact commits recorded during preparation. If the target moved in the meantime, the apply is rejected and must be prepared again; otherwise Pointy pushes the candidate to the remote.

After a successful apply, Pointy reloads the workspace, refreshes affected project and step statuses, records the applied changeset in the chat, and leaves the chat open so you can continue from the applied state.

Discarding a changeset

Click Discard changeset to throw away the agent's commits and reset the worktree to the current target-branch tip. A lifecycle turn is appended to the chat recording that the changeset was discarded. The chat stays open and you can immediately start a new conversation from the clean state.

Archive and permanent delete

Archive

When you are done with a chat and want to keep it for reference, archive it. An archived chat:

• Is moved to the archived section of the sidebar.
• Cannot accept new prompts (the prompt composer is replaced with a closed-chat notice).
• Keeps its full conversation history and changeset markers.

To archive, click the archive icon on the chat row in the sidebar.

Permanent delete

An archived chat can be permanently deleted. This removes its Git worktree, agent branch, turn logs, and session metadata from disk. Click the delete-forever icon on the archived chat row and confirm.

Working with agent changes outside Pointy

Applied changesets become ordinary commits on the target branch. You can inspect them, share them, and edit them with any Git tool:

• You can inspect agent changes with git log on the user repository.
• Other Pointy instances that share the same user-repository remote see applied changes after their next fetch.
• The agent works on the same projects/<id>.nix and steps/<id>.nix files that the UI and the backend API edit.

For the administrator's view of runner configuration, sandbox boundaries, secret provisioning, and retention, see Agent runner configuration in the Instance Admin Guide.