Remote control - solutionscay/skiff GitHub Wiki

You can use the Skiff agent, Skipper, from a phone. Connect to the computer that runs Skiff with an SSH app, for example Termius. Then use the skiff command in the SSH shell. You see the same sessions as in the app.

Before you start

You need these items:

SSH access to the computer that runs Skiff. Log in as the user that runs the app.
An SSH app on the phone, for example Termius. To detach from a session, the app must send Ctrl+\.
The skiff command on PATH in the SSH shell. If it is not there, open Skiff on the computer and select Help › Install skiff command….

Do a check of the connection:

skiff status

If the shell cannot find skiff, install the command as above.
If skiff status says that skiffd does not run, open Skiff on the computer. You can also run skiff skipper, which starts it.

Select the daemon

From SSH, skiff connects to the daemon of the installed app. You do not set anything.

To connect to a dev build, give its socket:

export SKIFF_SOCKET=$XDG_RUNTIME_DIR/skiff/skiffd-dev.sock

To use a socket for one command only, put --socket PATH before the command:

skiff --socket $XDG_RUNTIME_DIR/skiff/skiffd-dev.sock ls

See skiffd for the socket paths on each system.

Name a session

In an SSH shell, . and --group . do not work. Use one of these to name a session:

The full id.
A part of the id at the start that matches one session only.
The name that the sidebar shows.

Names can change. In a script, use the id.

List the sessions

skiff ls

For a table that fits a phone screen, run the report script with --mobile. The script needs Python 3 and Rich.

python3 ~/skiff-agent/.agents/skills/skiff-cli/scripts/session_report.py --mobile

The report does not send text to a session. It does not mark output as seen.

A session has one of these states:

State	Meaning
`working`	The program writes output.
`waiting`	An approval prompt or a bell. A person must answer it in the pane.
`idle`	No output for some time. The task is possibly not done.
`done`	The program exited.

Open Skipper

skiff skipper

The phone's terminal shows Skipper's session. You can read the screen and type, as in the app.

If Skipper does not run, the command starts it first.
If skiffd does not run, the command starts it too.
If Skipper's pane shows only a shell, the command starts the agent in it again.

To detach, push Ctrl+\. Skipper continues to run.

If you push Ctrl+C two times in 2 seconds, Skiff holds back the second one, so the agent does not stop by accident. Push Ctrl+C again to send it.

While you are attached, the pane in the app has the size of the phone's screen. When you detach, the pane gets its old size again. This also occurs if the SSH connection stops.

A logout from SSH does not stop Skipper or skiffd.

To get Skipper's session id and not attach:

skiff skipper --no-attach

Read Skipper's screen

To read the screen and not attach, use peek:

skiff peek Skipper
skiff peek Skipper -n 40

Use Skipper's name or the id from skiff skipper --no-attach. With -n 40, peek shows the last 40 lines. peek does not type into the session.

Send a message to Skipper

Read the screen with skiff peek Skipper.
Make sure that Skipper is idle and that its input box is empty.
Send the message:

skiff send Skipper "List the open tasks and their state." --enter

--enter pushes Enter after the text.

For a long message, write it in a file on the computer. Then send the file:

skiff send Skipper - --enter < prompt.md

If the text starts with -, put -- before the text.

Skiff does not keep a refused message for later. A refused send types nothing. Read the exit code in the table below. Then read the screen again later.

Follow the tasks in the ledger

The ledger is Skipper's list of tasks. Read it with these commands:

skiff ledger ls
skiff ledger ls --state pending
skiff ledger show UID

ledger ls shows the tasks, oldest first. The tasks of a plan show below the plan.
The LIVE column shows if the pane of the task still exists.
--state shows only the tasks in one state.
ledger show takes the row number or the 8-character uid.

State	Meaning
`sent`	The task went to its pane.
`pending`	The task did not go to its pane, because the pane was working.
`blocked`	The pane needs a person.
`done`	The task is closed.
`interrupted`	The pane started again after the send. The process of the task stopped.
`gone`	The pane does not exist now.

To read the pane of a task, get the pane id from skiff ledger show UID. Then run skiff peek on that id.

Result files are in ~/skiff-agent/results/. Read them with cat or less.

To see each state change when it occurs, run:

skiff events

events shows one line for each state change, exit or removal. It does not show screen text. It runs until you push Ctrl+C, or until --timeout N seconds go by. An idle line does not mean that the task is done. Read the screen with peek before you act.

Exit codes of `skiff send`

skiff send does a check of the session before it types. These are the exit codes that you can get from SSH:

Exit	Meaning	What to do
0	Skiff sent the text.	Read the screen later for the reply.
1	An error occurred. For example, no session has that name.	Do a check of the name or id with `skiff ls`.
3	The session is `waiting`, with an approval prompt or a bell.	Attach with `skiff skipper` or `skiff attach S`. Answer the prompt.
4	The session is `working`.	Read the screen again later. Do not send again at once.
5	A shell, or a program that Skiff does not know, shows in the pane.	If Skipper shows a shell, run `skiff skipper`. Use `--shell` only to type a shell command.
6	The session is `done`. Its program exited.	Start a new session.
8	The text went to a known agent, but no turn started in 5 seconds.	Run `skiff peek S`. The text can be in the input box.
9	The agent's input box has text, or the agent is busy. Skiff typed nothing.	Read the screen. Clear the text in the pane, or wait until the agent is not busy.

--shell changes only the exit 5 check. A program that you started with skiff new -- CMD shows a shell in the pane. A custom agent also shows a shell. To send text to them, add --shell.

send does not push Enter a second time. After exit 8, a second send gets exit 9 while the text stays in the input box.

Limits

Skiff does not send notifications to the phone. To find a pane that needs you, run skiff ledger ls --state blocked or skiff ls.
Skiff does not give access to the computer from outside your network. You must set up SSH access yourself.
The computer must be on and awake. The sessions run on the computer.
To answer an approval prompt, attach to the pane with skiff skipper or skiff attach S. send cannot answer it.
While you are attached from the phone, the pane in the app has the size of the phone's screen.
Do not stop skiffd with kill, pkill or killall. skiff daemon stop stops all sessions.

See CLI for all commands. See Skiff agent for the ledger.