Skip to content
AutoPhd-orgPublic

About

The launcher and the contract for a software ecosystem that people and their agents share.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

9 Commits

Folders and files

Repository files navigation

LaunchX

The launcher and the contract for a software ecosystem that people and their agents share.

LaunchX is two things. It is a launcher that runs your local apps from one place, with a Mac app you drive with the mouse. And it is a contract for how an app opens itself to both of its users: the person and the person's agent. This README starts with the thinking behind the contract. The practical part starts at Install.

Why · The philosophy · What the contract asks · Install · Commands · The contract

Why a new ecosystem

First there were LLMs, and all an LLM could do was chat. We wanted them to act, so we gave them tools and a loop to use them in, and the code around the model became the harness. From 2023 to 2026 most of the invention went into that harness, and it worked: an agent can now plan, call tools and work for hours.

The interface did not move. A person still tells an agent everything in words, in a chat session, and reads long text back. An agent still reaches software through the door that was built for people: a screenshot, a click, another screenshot, or one file after another, spending tokens to learn a state the app already knows.

Two pictures of the same pipeline: you, an agent, and software. In 2023 you write a prompt and read an answer, the agent executes a tool call or two, and the agent is the bottleneck. In 2026 the agent, inside a harness, plans, calls tools and works for hours, and the two links are the bottleneck: what you see has to become words, and the agent rebuilds the app's state from screenshots, clicks and file reads before the work starts.

So the limit is no longer the model, and it is no longer the harness. It is the place where the person, the agent and the software meet. Two questions follow from that:

  • Who said people must convey information in words?
  • Who said an agent must walk an app from its front to its back to read and change its state?

Answering them is interface engineering, and it is all this project does. LaunchX does not make a better model or a better harness. It describes software that a person and an agent can use together, and it runs that software.

The philosophy

Eight ideas shape the contract. Each is a claim about how software should be built now that it has two kinds of user.

1. An app can say what state it is in. Everything its page shows comes from one JSON document, and the page has no private channel, so nothing exists only on screen. An agent learns in one call what would otherwise take a chain of screenshots. The contract's test: someone holding only the documentation and a token could rebuild the whole page.

2. Every action is a command. Anything a person can do on the page, a command can do, and the result shows on the page at once. The command line is a peer of the page, never an afterthought. An agent acts in one step, and so can a script or another app.

3. The person holds the switches. An agent works on an app with its owner's authorization, never around it. In LaunchX every app is hidden from agents until you switch it on, and an app can let an agent propose a change that waits for your yes.

An app has one state document and a page that is one view of it. You use the page. Your agent reads the state and runs commands directly, through access switches you set for each part of the state. The route agents take today, through screenshots and clicks on the page, is drawn as a long detour.

4. The page is shared. An app's interface is a web page served by its own backend. It is the same page for you and for your agent's work: what the agent does appears where you are already looking, so it does not have to describe your own app to you in a chat.

5. Words are one input among several. On a shared page you can answer an agent with a button, a switch or a drag, and next with a pen or a shortcut key. The chat box stays for what is best said as a sentence. An app should offer the quickest way to say each thing.

One app window that you and your agent both use. On a task board, a task the agent suggested has Add and Reject buttons, a task you circled with a pen carries your handwritten note, and a task the agent just added can be undone. A bar lists shortcut keys. A side panel has switches for what the agent can see and do in each part of the app, and the chat box is still there.

6. Apps stay small; the launcher owns the plumbing. An app is handed its port and its token and runs in the foreground. Sign-in, logs, restarts, health and the order apps start in belong to the launcher, once, for every app.

7. Local first. Data lives in files you own, an app listens only on your own machine unless you decide otherwise, and anything private (the names of your machines, your organisation, your accounts) stays in a file outside the app's repository.

8. No side taken on models or harnesses. The contract asks nothing of an agent except that it can run a command and read JSON, so whichever model and harness you use next year will work. It asks little of software too: an app that has never heard of LaunchX joins with a manifest and no code changes.

The two pictures show where this is heading. Draft 0.1 of the contract already requires ideas 1, 2, 4 and 6, and is built around 7 and 8. For idea 3 it has two switches per app: whether agents are told about it, which decides what they are told rather than what they can reach, and what it may do with your shared memory, which LaunchX enforces on every request. A switch for each part of an app is not there yet. Idea 5 is up to each app today: buttons, switches and drags work, and the pen and the shortcut keys are still plans.

What the contract asks

An app describes itself in a launchx.toml manifest and claims one of three levels. SPEC.md has the full text and two worked examples.

Level The app must What it gets
0, described Have a manifest. No code changes. Start, stop, restart, logs and dependency ordering.
1, managed Run in the foreground on the port and token it is handed, and report its health. A port and a token from the launcher, health on its card, and its page at a stable signed-in address such as http://vmc.localhost:7600/.
2, open Expose its whole state as JSON and ship a CLI that can do what its page can. Agents, scripts and other apps can read it and drive it.

The launcher does the rest. It starts each app in the order its dependencies need, watches its health, keeps its logs, puts every page behind one sign-in, and has the switch that decides whether your agents are told about an app. lx check <id> tests an app against the level it claims.

LaunchX is part of AutoPhD, which builds apps on this contract. Status: contract draft 0.1, working launcher on macOS and Linux; the app is macOS only.

Install

Needs Rust (cargo) and, on macOS, the Xcode command-line tools (swiftc).

./install.sh            # macOS: LaunchX.app into ~/Applications, lx linked into ~/.local/bin
lx up                   # start the launcher now and at every login
lx install AutoPhd-org/schedule-everything   # install an app from its repository
lx add ~/code/my-app    # or register one that is already on this computer

On Linux install.sh copies lx into ~/.local/bin; use the browser page at http://launchx.localhost:7600/ (lx open). lx daemon runs the launcher in a terminal instead of at login.

The app (macOS)

Open LaunchX from Launchpad, Spotlight or ~/Applications.

  • Main window: every service as a card with its status, health, summary, version and port, plus Open, Start, Stop, Restart and Logs buttons. It is the launcher's web page, signed in automatically.
  • Install app takes a repository or folder, shows what installing it will run, and installs it. Apps installed this way get Update and Uninstall on their card, and a note when their repository has new commits.
  • Open sends a service's page to your default browser, already signed in (starting the service first if needed). After that, a bookmark such as http://vmc.localhost:7600/ signs in on its own for 30 days.
  • Menu bar (paper plane): each service with a coloured dot and Open / Start / Stop / Restart, without opening the window.
  • When the launcher is not running, the window offers a Start button (it runs lx up).

LaunchX is the only app: services stay in the browser, where they get tabs, bookmarks, Find and extensions. Quitting the app leaves the launcher and services running; they belong to the daemon, not the window. The app carries its own copy of lx, which ~/.local/bin/lx links to.

Commands

Command Does
lx ls Services with status, health, version, port and summary.
lx start <id> / lx stop <id> / lx restart <id> Control a service. Start brings up what it requires; stop first stops what requires it. Services you started come back when the launcher restarts (at login, after an update) until you stop them.
lx open [id] Open the launcher, or a service's page, in the browser.
lx logs <id> [-f] [-n N] Captured output, including the launcher's own notes ([launchx]).
lx install <source> Install an app from a git URL, owner/repo on GitHub, or a folder: clone it (a folder stays where it is), run the installer its launchx.toml names, register it. Asks first; --yes doesn't. With no source, lists what is installed.
lx update [<name>…] Pull each installed app and, when there is something new, run its installer again, restarting what was running. --check only reports.
lx uninstall <name> Stop the app, run its uninstaller, unregister it and delete the checkout LaunchX cloned. Your data stays, and it says where.
lx add <path> / lx rm <id> Register or unregister a manifest. rm removes the link in ~/.launchx/services, never the manifest.
lx check <id> Start a temporary copy on a spare port and test it against the level it claims.
lx state The launcher's full state document as JSON.
lx up / lx down Register or remove the launcher as a login service, and start or stop it.
lx agents / lx agents on <id> / lx agents off <id> What your AI agents can discover, and the switch for each service (see below).
lx memory Your shared memory: ls, show, write, append, rm, history, log, search, lint, index, open (see below).
lx memory access / lx memory access <id|agents> none|read|write Which apps, and whether your agents, may read or write your memory.

Every page of the launcher is also an API: GET /api/state, GET /api/events (server-sent events), POST /api/services/<id>/start. Programs reach it at http://127.0.0.1:7600 with the token in ~/.launchx/run/launchx.json.

Agents

Each service has a Discoverable by agents switch: on its card, in the menu bar, or lx agents on|off <id>. It starts off. While a service is on:

  • lx agents (and --json) lists it with its CLI, state, run file and skills;
  • its skills ([service.<id>.agents] skills = "…" in its manifest) are linked into ~/.claude/skills and ~/.agents/skills, whichever exist (agent_skill_dirs in config.toml);
  • a generated launchx skill tells your agent which apps it may use and how, and to leave the others alone.

Switching a service off removes what LaunchX put there; LaunchX never touches skills it did not create. The switch controls what agents are told, not what they can reach: an agent runs as you, so it could still find a hidden service if it went looking.

Shared memory

Every app you run should not have to ask who you are. LaunchX keeps one memory for you, a small wiki of Markdown pages (your profile, preferences, schedule, resume, projects, the people you work with) that your apps and agents read and write together. You decide, per app, whether it may read it, read and write it, or neither: on the app's card, in the page's Memory view, or with lx memory access <id> read. Every app starts with no access.

lx memory write profile --summary "PhD student in computer science, Pacific time" < profile.md
lx memory access rmd write          # Schedule Everything keeps the schedule page
lx memory access papers read        # the paper reader picks papers from your profile
lx memory access agents write       # publish the launchx-memory skill to your agents
lx memory log                       # who changed what, and why
lx memory open                      # browse, edit, see history and restore in the browser

It is built from the components of agent memory: a log of every write (the transcript), pages linked with [[page]] (the representation), and a short index of one line per page that an app or agent loads at the start of a session (the injected context). What keeps it trustworthy when many writers share it:

  • Nobody overwrites anyone by accident. An update names the revision it read; if the page changed since, it is refused with the current page, and the writer merges. The page does the same for you while you edit.
  • Each app writes as itself. An app gets its own memory token (LAUNCHX_MEMORY_TOKEN), which opens memory and nothing else, and its writes are logged under its id.
  • Nothing is lost. The version a write replaces is kept; lx memory history <page> and the page's History button show and restore the last 20.
  • It stays small. Pages hold up to 64 KB, the index up to 200 lines, and lx memory lint points out broken links, missing summaries, and duplicate, large or stale pages. Tidying is an agent's job, with your model: an agent with write access is told how in its skill.
  • It is yours. The pages are plain files in ~/.launchx/memory, editable with anything, and lx memory works when LaunchX is not running.

An app reaches memory through LAUNCHX_MEMORY_URL with its token (GET /api/memory/index, GET /api/memory/pages/profile, PUT with base, POST /api/memory/append/<page>), and can ask for access in its manifest with [service.<id>.memory] wants = "read" and a reason you see on its card. SPEC.md §12 has the details.

Files

~/.launchx (or $LAUNCHX_HOME), mode 0700:

config.toml        gateway_port = 7600, backoff_unit_ms = 1000
services/          links to registered manifests
run/<id>.json      URL, token and pid of each running service (mode 0600)
logs/<id>.log      captured output, rotated at 5 MB
agents/skills/     skills published to your agents, linked from their skill folders
memory/            your shared memory: pages/, history/ and log.jsonl
sources/<name>/    checkouts lx install cloned
installs.json      what lx install installed, from where, at which commit
state.json         assigned ports and tokens, the session secret, and the agents and memory switches (mode 0600)

Development

cargo test          # unit tests and an end-to-end run against fixture services

The end-to-end test starts a real daemon on a spare port with fixture services and covers dependency order, sign-in, the token swap, the Origin check, streaming and Upgrade through the gateway, restart back-off, lx check, the agents switch, shared memory (an app reading and writing with its own token under each access level, refused stale writes, the memory skill, lx memory without a launcher), and shutdown.

License

MIT. See LICENSE.

About

The launcher and the contract for a software ecosystem that people and their agents share.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages