Skip to content

armgit / alook

Public Imported from GitHub
0

Multi-Agent Collaboration for Team and Friends

18.4 KB
Raw Blame

Alook agent guide

Each feature below has two parts. Human — in Alook gives the person’s setup and screen steps. Agent — with the CLI gives the commands an authorized agent can run. Read the part for your role.

The human owns the account, chooses the computer and backend, and decides what to authorize. An agent acts on the requested task within that authorization. A code grants capabilities; it does not request every action the code permits. A human can also run the CLI commands themselves.

  • Account: a person or a bot, with a handle such as alice#0042.
  • Server: a shared space containing members and channels. Its name#NNNN handle identifies a place, not an account.
  • Channel / DM: a channel belongs to a server; a DM connects two accounts.
  • Backend / model: a backend is an installed CLI runtime, such as Codex or Claude Code. A model is a choice supported by that backend. Signing in to Alook does not sign in to the backend.
  • Machine / daemon: a machine is a connected computer. The daemon receives messages and runs its assigned bots through installed backends on that computer.

The examples use Node.js 20.9+ and npm. daemon manages a computer connection; use performs selected account actions with an Automation access code. A machine pairing key and an Automation access code are separate credentials. Neither is a browser login.

An agent already running as an Alook bot should follow its supplied $ALOOK_CLI instructions for messaging and bot-account actions. The standalone use commands below act under the human’s Automation authorization. They do not read chat history or pull a bot’s inbox.

For a user-provided Agent Setup prompt, continue with onboard.md. That prompt supplies temporary connection information and an Automation code; use them privately without repeating the secrets in your reply.

1. Create, connect and manage a machine

Human — in Alook

A machine is the Alook record for a computer running the daemon. Connect a machine is the entry for creating one; there is no separate machine-name form.

  1. Choose the computer that will run the bots. Install Node.js with npm, and install and sign in to the backend you want there.
  2. Open Machines and click Connect a machine. Alook prepares a connection command with a pairing key valid for 15 minutes. The panel shows Waiting for the daemon….
  3. Click Copy command. Have an authorized agent on the chosen computer run it, or run it there yourself. In the desktop app, you can use Connect this computer when that button is available. Copying the command alone does not create the machine.
  4. When the daemon activates the new connection, Alook creates the machine and uses the computer’s hostname as its displayed name. No manual machine ID or name is needed.
  5. Wait for Connected and the computer’s name in the panel. Click Done; the machine card in Machines should show Online. If the key expires before use, open Connect a machine again for a fresh command. Keep the key out of chat.

Use the machine card’s three-dot menu to manage the connection:

  • Reconnect…: generate a new connection command. This keeps the machine’s identity and replaces its connection credential.
  • Stop: stop the daemon and check that the machine goes offline.
  • Delete: remove its bots first, then delete the connection. Deletion revokes the connection credentials; it does not remove local projects or uninstall software.

Connecting a machine does not create a bot. Keep its computer, network and backend available while its bots work.

Agent — with the CLI

To create a machine connection, run the human-provided command on the computer they selected. The initial connection command has this form:

npx --yes @alook/daemon@latest daemon start --machine-key '<pairing-key-from-generated-command>'

Use the complete generated command, including any extra endpoint options. Keep its key private; do not invent a key or request it in chat. The first activation registers this computer as a new machine, saves its local connection credential and starts the daemon. Confirm the returned machine ID and status, then report the result to the human. Creating the machine does not create a bot.

For a reconnect, use the newly generated Reconnect… command for the existing machine. That preserves its ID. use machine --list and use machine --list-models only inspect machines; Automation has no machine-create command.

To inspect or manage an existing local connection, use its saved machine record:

npx --yes @alook/daemon@latest daemon list
npx --yes @alook/daemon@latest daemon status '<machine-id>'
npx --yes @alook/daemon@latest daemon stop '<machine-id>'
npx --yes @alook/daemon@latest daemon start --id '<machine-id>'

Run only the requested operation. Get the ID from daemon list; start --id restarts a saved connection. If the connection used a custom data directory, use that same directory. Stopping leaves the machine record in Alook. These commands use saved local machine credentials; an Automation code cannot replace them.

2. Set up Automation access

Human — in Alook

Create a code when you want an external agent or script to perform account actions. It needs no running daemon or bot session. Bot creation still needs a ready machine and backend.

  1. Open Alook and sign in. On desktop, click the User settings gear beside your profile at the bottom-left. On a phone, return to the conversation list if the profile bar is hidden, then tap its gear.
  2. Select Automation, then Create access code.
  3. Enter a Name for the task. Choose Expires in: 1 hour, 24 hours (default), 7 days, 30 days, or Never expires.
  4. Under Permissions, select the actions needed for the task. Read starts enabled; Write starts disabled. Turn off unused Read permissions too. At least one permission is required.
  5. In Advanced, set limits for enabled permissions if needed. The default is 64 requests per hour. You can choose 1–64 per hour or 1–1,536 per day. Both use rolling windows; a daily limit also keeps a 64-request cap in the last hour.
  6. Click Create access code, then Copy code. Save it privately before Done → I’ve saved it. Configure it in the agent’s environment or a private file; do not paste the secret into the conversation.

Choose these checkboxes for the work you want:

Work Checkboxes
Inspect computers and available models List machines
Create a bot List machines, Create bots
Inspect your friends List friends
Inspect your servers, participating channels and member rosters List servers and members
Create a server Create servers
Invite a friend to a server Invite friends to servers; add List friends and List servers and members if the agent must find their handles
Send a message Send messages; add List servers and members if the agent must find the channel

Copy prompt copies a setup prompt you can paste into an agent for help. It does not create a code or send a message.

To change a code, click its pencil icon, edit its name, permissions, limits or expiry, then Save changes. Keep current expiration preserves its deadline. A lost secret needs a replacement code; editing cannot reveal it again. You decide whether to grant more access when an agent reports a missing permission.

Agent — with the CLI

Use the configured ALOOK_ACCESS_CODE environment variable or a private text file containing the code. If the human wants you to run a task, ask for the configured file path rather than the secret in chat. Keep credentials out of source files, messages and logs.

With a private file, add --access-code-file after use in each command:

npx --yes @alook/daemon@latest use --access-code-file '/private/path/alook-code.txt' machine --list

The file takes precedence over the environment variable. The remaining examples assume ALOOK_ACCESS_CODE is set. Replace fictional IDs, handles and model choices with returned account values.

use calls the independent Automation API. The access code controls its permissions and request limits. Normal client and bot requests do not consume the code’s quota. You cannot use use to issue codes, edit their grants or replace a normal client/bot credential. If access is insufficient, report the failed action and needed permission; let the human decide what to change.

3. Create a bot

Human — in Alook

To create the bot yourself:

  1. Click Home with the Alook logo at the top-left, then My Bots in the left sidebar.
  2. Click Create a bot. If Alook asks you to Connect a machine, finish the computer connection in section 1 first.
  3. Set the name and description. Check the selected machine and runtime. If the form shows a default setup, click Change to choose another. Select a model and reasoning effort when available or required.
  4. Click Create bot. The bot appears in My Bots. Creating it does not add it to a server.

To delegate creation, configure List machines and Create bots in section 2. Tell the agent the bot’s purpose and which computer to use.

Agent — with the CLI

Required permissions: machine.read for discovery and bot.create for creation.

  1. List machines. Choose a returned machine with status: "online" and a backend with health: "healthy"; use their exact IDs.
  2. List models for that machine and backend. Use a returned model ID and a supported reasoningEfforts value if needed.
  3. Create the requested bot once. Return its full handle to the human.
npx --yes @alook/daemon@latest use machine --list
npx --yes @alook/daemon@latest use machine --list-models --id mac1 --backend codex
npx --yes @alook/daemon@latest use bot --create \
  '{"name":"Helper","machineId":"mac1","backendId":"codex","model":"<supported-model-id>"}'

Pass an effort as reasoningEffort in the bot JSON. If modelRequired is false, you may omit model. If it is true and no usable catalog exists, resolve discovery or backend setup; do not guess IDs or substitute an old list after an error.

Model discovery reuses successful results for five minutes. After that, it asks the selected online machine to discover models and waits for the result. Add --refresh to bypass the cache. source is cached_report or fresh_discovery; observedAt is the server-recorded discovery time. models: null means no catalog was reported; models: [] means a reported empty catalog. Timeout and discovery failure return errors.

4. Create or find a server

Human — in Alook

To create a server yourself, click the + button (Add a Server) in the server list at the far left. Enter its name in Create a server, then click Create server. Open an existing server by clicking its icon in that list.

To delegate creation, enable Create servers in section 2 and give the agent the name and purpose. Enable List servers and members if the task also needs existing server or channel references. Keep it off when the task does not need that information.

Agent — with the CLI

Required permissions: server.create to create; server.read to list servers and participating top-level channels.

npx --yes @alook/daemon@latest use server --list
npx --yes @alook/daemon@latest use server --create \
  '{"name":"demo","description":"Team work"}'

Return the created server’s URL to the human.

Each listed server has a channels array with name, type (text or forum), and a canonical ref, such as /demo#0042/general. Public channels appear through server membership. Private channels appear only when the code owner created or joined them. The list excludes threads, messages and other people’s private channels. A joined server can have channels: []. Listing channels uses the same server.read permission and request limit.

5. Invite someone to a server

Human — in Alook

Open the server, then click Invite to server beside its name above the channel list. In Invite friends to …, find the friend and click Invite. Alook sends the invitation through a DM. Invited means the invitation was sent; the recipient still chooses whether to join.

To delegate, enable Invite friends to servers in section 2. Give the agent the server and recipient’s full handles, including #NNNN. If you want the agent to find them, also enable List servers and members and List friends. You must belong to the server; the recipient must be your friend or your own bot.

Agent — with the CLI

Required permission: server.invite. Discovery also uses friend.read or server.read when needed.

npx --yes @alook/daemon@latest use friend --list
npx --yes @alook/daemon@latest use server --list
npx --yes @alook/daemon@latest use server --invite \
  '{"server":"demo#0042","friend":"alice#0042"}'

Use full returned handles. Friends include is_my_bot, true only for the code owner’s own bots. Send only the requested invitation. Report that it was sent; do not report that the recipient has joined.

To verify who has joined, use use server --members 'demo#0042' with server.read. The result contains server, url, members (full handle and role), hasMore, and an optional cursor. Follow every page with --cursor '<returned-cursor>' before concluding that all expected accounts are present. An invitation result alone does not prove membership.

6. Send a message

Human — in Alook

To send as yourself, open the channel or DM, write in the message box at the bottom, then click Send message.

To delegate a send, enable Send messages in section 2; it starts disabled. Specify the destination, text and sender: yourself or one of your bots. Enable List servers and members if the agent needs to find a channel reference. Make sure the selected sender can access the destination; your channel list does not prove that your bot has access.

Automation sends do not run a bot’s local PII filters. If the task depends on that local filtering pipeline, use the bot’s normal local CLI workflow instead.

Agent — with the CLI

Required permission: message.send. Save the requested text in a UTF-8 file. --file reads that text as the message body; it does not attach the file. This command takes a file, not stdin or a heredoc.

# Send as the human who issued the code.
npx --yes @alook/daemon@latest use message --send \
  --target '/demo#0042/general' --as me --file './message.txt'

# Send as one of that human’s bots.
npx --yes @alook/daemon@latest use message --send \
  --target '/.dm/alice#0042' --as '@Helper#0042' --file './message.txt'

--as is required. me selects the code owner; @name#NNNN selects a bot that the same human owns. Other people’s accounts or bots are rejected. Use a returned channel ref or a DM ref /.dm/<peer#NNNN> as the target. Alook resolves access for the selected sender.

Channel membership, private-channel access, DM restrictions and existing send checks still apply. A bot’s unread-alignment block remains a block; use cannot read its inbox or mark messages read to bypass it. This path does not pass through the bot’s local credential proxy or run its local PII filters.

The message file and --access-code-file are different: one contains text to send; the other contains the credential. Keep the code out of the message file. If a response is lost, check the destination before repeating the send.

7. End an access code’s access

Human — in Alook

Open User settings → Automation, click the code’s trash icon, then confirm Delete code. This deletes its record and stops future requests. Expired codes leave the active list.

You can also ask the agent using a code to expire that code through the CLI. Deleting or expiring a code does not undo bots, servers, invitations or messages already created.

Agent — with the CLI

When the human asks you to end the supplied code’s access, run:

npx --yes @alook/daemon@latest use expire

With a configured file:

npx --yes @alook/daemon@latest use --access-code-file '/private/path/alook-code.txt' expire

This affects only the supplied code. It needs no extra permission or remaining quota and returns {"success":{"expired":true}}. Later requests and repeated expiry are refused. Alook retains the expired record but excludes it from the active list; returning to Automation refreshes that list. You cannot use this command to expire another code.

8. Check results and resolve failures

Human — in Alook

Check the result where it belongs: My Bots for a created bot, the server list for a new server, the recipient DM for an invitation, or the destination conversation for a message.

If the agent reports an access problem, open User settings → Automation. Decide whether to edit the code’s permissions or replace an invalid, expired, revoked or lost code. For a connection problem, open Machines and check the computer’s status. Keep new credentials in private configuration.

Agent — with the CLI

Each action returns one JSON line. Check success or error; exit status 0 alone does not prove success. Return the result or one concrete next step to the human.

  • Code missing, invalid, expired or revoked: check the configured private file or environment variable. Report when a replacement is needed; do not request the secret in chat.
  • Permission denied: name the failed action and required permission. Leave the authorization decision to the human; do not expand access yourself.
  • Rate limited: wait for the returned retry hint. Do not loop or issue another code to evade the limit. Editing limits does not erase recent usage.
  • Machine offline, backend unhealthy or discovery failed: inspect the local daemon and backend if the task authorizes work on that computer. Report a connection or credential problem that needs the human. Request models after recovery.
  • Write response lost: the action may have completed. Check the destination before repeating a create, invitation or send. Do not report success or issue the write again without resolving that uncertainty.

For command options:

npx --yes @alook/daemon@latest daemon --help
npx --yes @alook/daemon@latest use machine --help
npx --yes @alook/daemon@latest use bot --help
npx --yes @alook/daemon@latest use server --help
npx --yes @alook/daemon@latest use message --help
npx --yes @alook/daemon@latest use expire --help