dira

Authentication

The long-lived token workers use is for Claude only. A worker whose engine is another CLI, like codex, never even looks at the token file and uses its own authentication. Which worker runs on which engine is decided by the persona (Workers §The persona decides the engine and the model).

Authenticating in the browser

Press the gear at the far right of the header and Settings opens. Authentication › claude in the left tree is this chapter's screen. From the top down, it looks like this.

  1. What you need - the path of the executable the app found, after claude CLI —. If it did not find one, No claude CLI here — workers can't start a session.
  2. Accounts - registered tokens, one per line. A name you can recognize, a state badge, the value masked except for its head and tail, and <date> added make up one row. Rename with the pencil on the right, delete with the trash can. With nothing entered yet, there is only the line No tokens yet.
  3. The Add button - one button under the list. With a token already there, the label becomes Change. Press it and issuing a token and entering one by hand open together in one popover.

If the first line says it did not find one, the rest is no use. Getting a token and opening a session when a worker takes a ticket are both jobs for that executable. If it is installed and still not found, quit the app and open it again. If that leaves it as it was, go back to Install.

Press Start sign-in at the top of the popover and the app walks through the official CLI's issuing procedure (claude setup-token) for you. There is nothing for you to type in a terminal. The CLI opens a new tab, and progress appears line by line in the log under the button.

  • When the browser shows you a code, paste that code into the Code from the browser field and press Send code. Sometimes approval alone finishes it. If that context is already logged in and consented at claude.com, it flows through without a code. The field is there for answering when you are asked.
  • The app stores the token where it belongs. There is nothing for you to copy over, so the progress log shows the token masked. The original never lands in a screen share or a screenshot.
  • Pressing it is already issuing it. If the browser opened, a flow that creates credentials under your claude.com account has begun, and there is no place to undo it.
  • If it breaks, it shows you the reason verbatim. What the app is doing is reading someone else's CLI screen, so it can break when that wording changes. The field below is the floor you land on when it does.

The Token field at the bottom of the same popover stays there after issuing. Paste a token you already have and press Save and it goes to the same place with the same authority. The token in use becomes the one you just entered. Label (optional) below it is the name you will recognize in the list. Leave it empty and it gets a number, like Account 1.

Validation checks two things only: that it is not empty, and that there is no whitespace or newline inside the value. Line breaks that came along with the copy are stripped by the app. It does not filter by prefix format. That format is not ours, and if it changes we would start rejecting perfectly good tokens. So the screen tells you no more than Saved. Whether it works shows up on the next dispatch.

agy - the engine that runs only while you are logged in to the Mac

agy does not put a token into the app. Its authentication lives in the macOS login keychain, and the app only borrows it. So before agy workers run, a person has two things to do ahead of time.

  1. Check that the agy CLI is on PATH. Type command -v agy in a terminal. One line with a path means it is. If the agy row in Settings › Authentication says Not installed, this step is missing. If it still says so after you installed it, quit the app and open it again.
  2. Launch agy once on the Mac's own screen and finish logging in. Run agy in a terminal and go through the login it shows to the end. The authentication is then saved in the login keychain. Do it in a terminal on the screen of the Mac you sit in front of, not in a remote shell.

dira does not run agy with an API key (GEMINI_API_KEY). That is billed per token, so dira calls agy -p as is, with the account you logged in with.

A worker started by cron cannot open the login keychain itself. So dira hands the agy command over to the screen where a person is logged in, runs it there, and takes back only the result. This comes with one condition. While you are logged out of the Mac, agy workers do not run. The session then ends right away instead of waiting, and the log gets this line.

agy-gui: GUI 세션 없음 - 로그인한 상태에서만 agy 워커가 돈다
text

When you see it, log in to the Mac again. agy workers run again from the next dispatch. If authentication still stops them after you log in, do step 2 again.

When a Chrome login window keeps opening

When agy cannot find the saved authentication, it opens Chrome and asks you to log in again. Because a worker launched that agy, the window opens on your screen. dira cuts the session as soon as it sees this, and leaves the two lines below in the log. The first appears when the session is cut, the second right after it in runner.log. The lines are in Korean as the engine writes them.

agy-gui: agy 로그인 필요 - 맥 화면의 터미널에서 agy를 한 번 띄워 로그인을 마친다
NOTE agy 로그인 필요 - 1800초 쿨다운
text

The first line says what to do: launch agy once in a terminal on the Mac's screen and finish logging in. Sit at that Mac, run agy in a terminal there, and finish the login to the end. It is the same as step 2 above. You can close the window already open in Chrome.

The ticket that was cut goes back to the backlog. For the next 30 minutes no ticket goes to an agy worker, so the Chrome window opens at most once every 30 minutes. Workers on other engines keep running in the meantime. Once you have logged in, agy workers take tickets again from the first dispatch after the 30 minutes are up.

The notification bell - the first item when there is no token

Before you get to live through "the workers are running and nothing is happening," the screen tells you first. It comes up as the first item in the notification bell in the project screen header: No Claude token · Workers still claim tickets, but they can't open a session and end right there. The Save a token button on that item opens the dialog above, right where you are. There is no screen to move to.

  • On the project screen the gear button itself changes too. Needs auth appears next to the icon.
  • It does not appear in a project with no claude workers. It does appear if the workers could not be read, though. Turning "cannot tell" into "it is fine" would bring back exactly the silence this chapter is trying to close.
  • There is no button to dismiss it. Put a token in place and the check turns itself off.
  • Expiry cannot be announced in advance. The expiry time is not written in the file and the CLI does not tell us. What breaks the silence after an expiry instead is the next item in the bell (Workers that die the moment a session opens:). See The screens.

Cloud mounts - Full Disk Access

This applies only when the queue root is on a mount such as Google Drive. When a process started by cron tries to read a file in a protected location, macOS blocks it silently, with no error. It looks as though the file is not there.

Open System Settings › Privacy & Security › Full Disk Access. cron itself does not appear in the list, so press +, then Cmd+Shift+G, and type /usr/sbin/cron in directly to add it. What actually reads the file is not the worker script but the cron daemon that starts it. It may not take effect right away even after you turn it on, so run a worker once by hand from the workers screen and check that the queue is visible.

App Management - the permission it asks for on every worker

Add a worker and the app writes a line to crontab, and macOS asks for the App Management permission at that moment. Registration stops until you answer, and pressing Allow carries it through to the end. The trouble is that this approval does not survive to the next registration. The same window comes up again every time you make one more worker (How many to run at once). The place to turn it on ahead of time, or to check it, is System Settings › Privacy & Security › App Management.

Without the app - using the engine alone

If you skip the app and run tick.sh alone, you have to do by hand what the dialog above does. What comes out is the same single file. Open a terminal and enter these three lines in order.

mkdir -p ~/.config/dira
claude setup-token
printf %s '<token>' > ~/.config/dira/oauth-token && chmod 600 ~/.config/dira/oauth-token
bash

That is: write the token claude setup-token produced into ~/.config/dira/oauth-token on one line with no newline, and lock it to the owner alone with chmod 600. It is the same path the app saves to, so whichever way you put it in, workers read the same file.

The token lives on the machine, and there is one of it. Even with the queue root on a shared drive, ~/.config/dira is a place local to this machine that does not sync. That is why moving or sharing the queue does not spread the secret with it. If you run workers on several machines, you have to get one on each.

Next is Engine MCP.