Agent Clip: a Pinix Clip that runs an agentic loop with memory, vision, and shell-style tools

The problem is where the agent loop lives, not whether it exists

Most agent frameworks ship as a library you import, a server you run, or a CLI you install next to your other tools. Agent Clip takes a different position: the agent is a Pinix Clip, meaning it is packaged, installed, and upgraded through the Pinix host's own clip mechanism. The README describes the target as "AI Agent as a Pinix Clip" and the build section shows the delivery artifact is dist/agent.clip, installed with pinix clip install and updated with pinix clip upgrade. That is the specific problem being solved. If you already run Pinix, you do not stand up a second runtime, a second config file, or a second upgrade path for the agent. It arrives as another clip. The audience is therefore narrow and identifiable: developers who have Pinix installed and who want an agent that can call other clips, including what the README calls Edge Clips such as iPhone capabilities. If you are not running Pinix, most of the distinctive machinery here (pinix-data:// URLs, clip invocation, ReadFile RPC) has no host to talk to, and the project reduces to a chat loop with file tools.

Runs, topics, and the three-layer memory model

The unit of work is a Run, defined in the README as "a single agentic loop cycle, from user message to the LLM's finish_reason: stop." One send can therefore involve several LLM calls and several tool executions, and the Run is what the caller polls or cancels. Messages belong to Topics, named conversation namespaces stored in SQLite and sorted by last message time. A topic is created automatically on first send or explicitly through create-topic. Memory is split into three layers with different lifetimes. Facts are persistent notes written with memory store and removed with memory forget. Summaries are generated per Run by the LLM and stored with an embedding. Semantic search runs cosine similarity over those summary embeddings, and memory search combines that with keyword matching via a -k flag. This is a conventional design and it is worth saying so plainly: summary-plus-embedding retrieval over a single conversation store is the default shape of most agent memory systems. What is less common is that the memory surface is reachable from the same command language as the file tools, so the model can search its own history mid-Run without a separate tool-calling protocol.

The tool interface is a pipe-friendly command language

Rather than exposing tools as JSON schemas, Agent Clip exposes them as commands the model writes as text: ls, cat, write, stat, rm, cp, mv, mkdir for files under data/, memory subcommands, topic subcommands, clip invocation, and browser actions. The README explicitly lists Chaining as cmd1 | cmd2 && cmd3 ; cmd4, and includes grep, head, tail, and wc as "pipe-friendly" text utilities. That choice has a real consequence. The model composes operations instead of selecting one function per turn, which collapses multi-step work into fewer round trips and matches patterns LLMs have seen in shell training data. The cost is that there is no schema to validate against. A malformed pipeline is a runtime error inside the loop, not a rejected tool call, and the README does not describe a parser specification or an error taxonomy for these commands. File operations are scoped to data/, which is a sensible boundary, and write -b takes base64 input, which is how binary artifacts such as images enter the store. The same command set is reachable externally: send, create-topic, list-topics, get-run, cancel-run, and config form the Pinix ClipService.Invoke surface.

Vision is a side effect of the browser tool

The vision path here is not a separate image pipeline. When the agent calls browser screenshot, the screenshot is saved to data/images/ and attached as vision content on the LLM API call. The README states the LLM can "see" screenshots it takes, and the returned text includes a Render line with a pinix-data://local/data/images/... URL. The same URL format is returned by write -b for images, so the chat UI renders both agent-written charts and browser captures through one protocol. That protocol is resolved by Clip Dock on Desktop and iOS, which fetches the file over Pinix ReadFile RPC. This is a clean design because it keeps binary data out of the message stream and lets the host decide how to display it. It is also tightly coupled to the host. Outside Clip Dock, a pinix-data:// URL is just a string, and the README does not describe a fallback. If you want agent vision in a plain web deployment, you would be reimplementing the resolver.

Getting it running takes two toolchains

The quick start assumes both Go and Node are present. make dev builds the macOS binary and initialises data/ from seed/, then you install frontend dependencies with cd ui && pnpm install && cd .., add an API key to data/config.yaml, and send a first message with bin/agent-local send -p "hello". The frontend build is make ui, which compiles ui/ into web/. Deployment splits by target: make deploy cross-compiles linux/arm64 and builds the frontend for workdir mode, where Pinix reads the repository directly and changes are live; make package produces dist/agent.clip for pinix clip install and pinix clip upgrade, and the README notes that upgrade preserves data/. Configuration lives in data/config.yaml, which the README says registers clips and holds the API key, and it can be read or changed at runtime through the config command with config set <key> <value>. The README is truncated mid-sentence in the configuration section, so the full key list is not available in the supplied material and I cannot enumerate it. The UI stack is React, Vite, and Tailwind CSS v4, with Streamdown for Markdown and plugins for Shiki code highlighting, CJK typography, KaTeX math, and Mermaid diagrams.

The build matrix and the missing licence are the two hard edges

Two constraints stand out. First, the documented build targets are macOS for local development and linux/arm64 for the BoxLite VM. There is no documented Windows or linux/amd64 path, so if your Pinix host runs on x86 Linux you are outside what the Makefile table describes and would need to add a target yourself. Second, the repository metadata supplied here lists the licence as unknown and the README contains no licence section. For a component that runs an LLM loop with file write access inside your data directory, that is a blocking gap for most organisations. It is not a reason to assume the project is unlicensed, only a reason to check the repository directly before you depend on it. A third, softer limitation: because tools are a text command language, the failure mode when the model writes a plausible but wrong pipeline is a partially completed Run, and cancel-run is the recovery path. The README does not describe transactional rollback of file operations within a Run, so a cancelled Run may leave files written.

Compared with a framework like LangChain or a hosted agent runtime

The obvious alternative for someone reading this is a general agent framework where tools are declared as typed functions and the runtime handles retries, tracing, and provider abstraction. The difference in approach is stark. A typed-function framework validates the call before execution and gives you a schema to render in a UI; Agent Clip gives the model a shell and trusts it to compose. That trades safety rails for expressiveness and fewer round trips. The second alternative is a hosted agent product, where memory, vision, and tool execution are managed for you. Agent Clip's counter-position is locality: topics and memory live in SQLite under data/, files live under data/, and the whole thing upgrades with pinix clip upgrade without a migration step for your data directory. If your reason for wanting an agent is that it can reach other services in your Pinix installation, the framework comparison is almost irrelevant, because neither a generic framework nor a hosted product has a clip pull/push mechanism or knows about Edge Clips on an iPhone.

Maintenance cost and who this is actually for

The maintenance surface is two toolchains plus a host dependency. You maintain a Go binary, a React frontend, and a data/config.yaml that must stay compatible with Pinix's clip registration format. The upgrade path is the cheapest part: make package then pinix clip upgrade dist/agent.clip, with data/ preserved, which is a better story than most self-hosted agents that require you to migrate a database by hand. The cost is that you are tracking Pinix's ClipService.Invoke protocol and its ReadFile RPC, and the README gives no version compatibility statement. There are no releases retrieved for this repository, so there is no changelog to read before upgrading. That means the practical upgrade discipline is to build dist/agent.clip from a known commit, install it into a non-primary Pinix instance, and confirm that an existing topic still loads and that a browser screenshot still renders before touching the instance you use. The last push recorded is 2026-05-17, which tells you the project is active but not how stable the interfaces are. If you need a component with a stated licence and a versioned release history, this is not it yet.

Editorial conclusion

Adopt Agent Clip if you already run Pinix and want the agent loop to live inside the same Clip install and upgrade path as your other services, because that is the only environment where the pinix-data:// rendering, clip pull/push, and Edge Clip invocation actually resolve. Do not adopt it if you need a permissively licensed component you can vendor, since the repository as supplied states no licence, or if you need a stable tool contract, because the run interface is a text command language. Verify three things first: the licence file in the repository, whether data/config.yaml accepts the model keys you intend to use, and whether make package produces dist/agent.clip on your target architecture, since the documented build targets are macOS local and linux/arm64 only.

Official sources

1. epiral/agent-clip on GitHub
2. Issues
3. README