How Lapu AI Works: Agent Loop, Permissions, Local Execution

If you have only used chatbots, you might wonder how Lapu AI works differently from typing a prompt into ChatGPT. The short version: Lapu is a desktop AI agent that runs natively on macOS and Windows, executes tools on your machine, and asks for permission before doing anything sensitive. This post is a technical walkthrough of how Lapu AI works in practice — the agent loop, the permission system, the audit trail, and the local-first architecture that ties it together.

The agent loop in detail

When you hand Lapu a task, it does not produce a single response. It runs an agent loop — a cycle of plan, gather, execute, observe, adapt — that continues until the task is complete or you stop it. This is the same architectural pattern Anthropic describes for its computer use tool, where the model "responds with a tool use request" and the application "responds to Claude with the results of evaluating that request," repeating until no more tools are needed (Anthropic, 2024).

The five phases:

• Plan. The agent decomposes your request into concrete steps. For "refactor the auth module to use JWT," it identifies which files it expects to touch, which tests to run, and what would count as "done."
• Gather. It reads context — opening files, listing directories, running read-only shell commands like git log or ls. Nothing is mutated yet.
• Execute. It runs one tool call at a time: write this file, run this command, click that button. Anything above the read-only tier surfaces a permission prompt first.
• Observe. After each tool call, it reads the result — the test output, the new file contents, the error message — and decides whether the plan still holds.
• Adapt. If a step fails or returns unexpected output, the agent revises the plan. It might rerun a failing test with verbose flags, back out a bad edit, or ask you a clarifying question.

The loop terminates when the agent reports completion, when it hits an unrecoverable error, or when you cancel. There is no fixed step count; a one-line rename ends in two iterations, a multi-file refactor might take twenty.

How the agent reasons

Lapu uses frontier language models to drive each step of the loop. The model decides what tool to call next, what arguments to pass, and how to interpret each result. The AI capabilities are built directly into the agent — there are no API keys to manage, no model settings to configure, and no provider decisions to make.

The reasoning happens in two places. Local reasoning includes deterministic checks the agent runs on your machine: validating paths exist, normalizing arguments, evaluating whether an action falls inside the current workspace. Model reasoning happens when the agent sends relevant context to the model provider over Lapu's infrastructure, gets back the next planned action, and routes it to a local tool.

This split matters because the boundary is also the security boundary. The model never executes anything; it returns a structured request, and the local agent decides whether to honor it.

Where the AI runs

Lapu is local-first. The agent itself — the loop, the tool implementations, the permission engine, the audit trail — runs entirely on your machine. File reads happen on your filesystem. Shell commands run in your terminal. Browser automation drives your local browser, not a cloud sandbox.

The frontier model itself runs on the provider's infrastructure, reached over Lapu's API. When the agent needs the model to reason about something, it sends the minimum context required — typically the current step plan, recent tool results, and relevant file snippets — and gets back the next action to take. Files are not stored remotely between requests. There is no cloud workspace holding your data.

This local-first architecture has three concrete consequences:

• OS-level permissions apply. The agent runs as your user account, with the same filesystem and network permissions you have. macOS Gatekeeper, Windows Defender, and your firewall all see it as a normal application.
• No multi-tenant blast radius. A bug in someone else's session cannot leak into yours. There is no shared cloud workspace to compromise.
• You can audit traffic. Because the only outbound calls are to the model API, you can verify with tcpdump or your firewall what the agent is actually sending.

Permission tiers

Trust is the hardest problem in AI agents. You want the agent powerful enough to be useful, but bounded tightly enough that it cannot quietly cause damage. Lapu solves this with a four-tier permission system, modeled on the risk categories the NIST AI Risk Management Framework recommends for managing AI system risk through clear governance and human oversight (NIST, 2023).

Tier	Examples	Approval
Read-only	file:read, dir:list, screenshot, git status	Auto-approved inside workspace, logged
Reversible write	file:write to workspace, append, rename inside workspace	Auto-approved with one-line preview, logged
Sensitive write	file:delete, write outside workspace, modify system settings	Per-action confirmation with preview
External action	shell:run, browser:control, send email, run a paid API	Per-action confirmation with full command and rationale

Each permission is scoped by tool, target, and duration. A single approval to delete one file is not a license to delete another. Scope-once is the default; scope-for-session exists but never scope-forever.

Granting a permission is a four-field decision: which tool, what target (path, command, URL), how long (this call, this session, this project), and what rationale (one sentence linking back to your original ask). Every approval writes that record to the audit trail.

What the audit trail captures

Every action Lapu takes is recorded. For each tool call the audit trail captures:

• Timestamp. ISO 8601 with millisecond precision, in UTC.
• Tool name and version. file:write@1, shell:run@2, etc., so you can correlate behavior across releases.
• Parameters. The exact path, command, URL, or text the agent passed. Long arguments are stored in full, not truncated.
• Permission state. Whether the action was auto-approved (and under which scope), explicitly approved, or rejected.
• Outcome. Exit code, return value, error message, and a hash of any file modified.
• Originating step. The plan step that triggered this call, so you can trace one bad action back to the model output that requested it.

You can replay any session and see exactly what happened. The trail is local — stored in a SQLite database under your user data directory — and never sent off your machine unless you export it. This is what we mean by permission-based execution: not just "you clicked Approve" but a forensic record of every step. For the field-level breakdown of what a strong AI audit trail needs to capture, the audit-trail explainer walks through every record type.

Worked example: organize Downloads

Concrete is better than abstract. Here is one task end-to-end.

Your prompt: "Organize my Downloads folder by file type and date. Move old screenshots into a Screenshots/2025 subfolder."

Plan phase. The agent breaks the request into four steps: list the folder, group files by extension and modification date, propose a new layout, execute the moves. It shows you the plan before doing anything.

Gather phase. The agent calls dir:list on ~/Downloads. This is a read-only action inside your home directory; it is auto-approved and logged. The agent reads back 384 files totaling 12 GB.

Plan refinement. The agent groups files: 47 PNG screenshots, 112 PDFs, 89 ZIPs, 136 other. It proposes folders: Downloads/Screenshots/2025/, Downloads/PDFs/, Downloads/Archives/. It shows you the full plan and waits for approval.

Execute phase. You approve. The agent begins moving files. Each file:move is a reversible write inside the workspace, so it is auto-approved tier-2 with a single-line preview in the activity log: move Screenshot 2025-09-12.png → Screenshots/2025/. The agent does these in batches of ten and pauses after each batch to check the result.

Observe phase. Halfway through, one file is open in another app and the move fails with EBUSY. The agent reads the error, logs it, and adapts: it skips that file and continues. At the end it reports four files skipped with their paths and the reason.

Audit trail entry. You open the activity panel an hour later. You see 380 successful file:move calls, four skipped, two dir:list calls, and the original plan with your approval recorded against it. If you want to undo, every move is in the log with both source and destination paths.

That is one task. Each phase happened on your machine. Nothing left your computer except the model's reasoning context.

Real-world workflows

The Downloads example is mundane on purpose. The same loop handles more substantive work:

• Code reviews — "Review the last 5 commits, check for security issues, summarize with recommendations."
• Data processing — "Read all CSV files in this folder, combine them into a single dataset, clean the formatting, generate a report."
• Project scaffolding — "Create a new Next.js project with TypeScript, Tailwind, ESLint, and a CI pipeline."
• Research synthesis — "Open these five PDFs in the workspace, extract every quoted statistic, group by source, output a markdown summary."

Each one runs through the same five-phase loop, the same permission tiers, and the same audit trail. The difference between a one-minute task and a thirty-minute task is the number of iterations, not the architecture. For developers and other power users, the same loop drives multi-hour refactors. The same loop also powers everyday desktop automation across your real apps.

Try it yourself

The fastest way to understand how Lapu AI works is to run a task on a throwaway folder and watch the prompts. Download Lapu AI for macOS or Windows, point it at a directory you do not mind getting reorganized, and ask for something concrete. The first time the agent pauses and shows you a Delete preview before executing, the architecture stops being abstract.

FAQ

What is the agent loop in Lapu AI?

The agent loop is a cycle of reasoning, planning, acting, and observing that runs until your task is complete. When you give Lapu a goal, it breaks it into steps, executes each one, checks the result, and adjusts the plan based on what it observed. This is fundamentally different from a single prompt-and-response chatbot interaction.

Where does Lapu AI execute tools — locally or in the cloud?

Tool execution is local. File reads and writes, shell commands, and application control all run on your machine. There is no cloud workspace and no remote file storage. Only the context needed for reasoning is sent to AI model providers via Lapu AI infrastructure; your files and command outputs stay on your desktop.

How does Lapu AI's permission system work?

Actions are categorized by risk. Read-only operations like listing a directory are auto-approved. Reversible writes inside the workspace are auto-approved within scope. Sensitive writes — deleting files, modifying system settings, writing outside the workspace — require per-action confirmation. External actions like shell commands or sending email require confirmation with an action preview.

Can I customize what Lapu AI is allowed to do without asking?

Yes. You can adjust permission thresholds per project or globally. Auto-approve read operations in a specific workspace, require confirmation for every action, or set custom rules for specific tools. The defaults are conservative; you opt in to looser policies, not out of stricter ones.

Do I need to configure an AI model or API keys?

No. Lapu AI uses built-in frontier language models. There is nothing to configure, no model provider account, and no API keys. You install the app, sign in, and start describing tasks in plain language.

Sources

1. Computer use tool — Anthropic (2024-10-22) · accessed 2026-05-13
2. AI Risk Management Framework — NIST (2023-01-26) · accessed 2026-05-13