Friday

A coding agent for your terminal. It shows its work, asks before it changes anything, and proves a change works before it calls it done. Bring any model: your own key for one of ten providers, free models, your Claude subscription, or your ChatGPT plan.

npm install -g @archymedes/friday
cd your-project
friday

That is all. The first run walks you through choosing a model; then you type what you want done.

Contents

• Getting going: Why Friday · Start in three steps · Choose your model
• Using it: How a request runs · Modes · Helpers · The interface · Commands
• Trusting it: What keeps your code safe · Make it yours
• Everything else: Scripts and editors · Questions · Requirements

Why Friday

Start in three steps

1. Install it. npm install -g @archymedes/friday puts a single friday command on your machine.
2. Run it in a project. cd into a folder with code and type friday. A short walkthrough asks for your name, a theme and a mode, then which model to use. Pick a provider, paste its key, and choose a model from the list it sends back. Choosing Claude or Codex signs in through those tools instead.
3. Ask for something. Type a request and press enter:

friday                                          # open a session in this folder
friday "fix the failing test in src/parser.ts"  # open it with a request already sent
friday --resume latest                          # carry on where you left off
friday --free                                   # free models only, never a paid one

friday --help lists every option, and / inside a session lists every command.

Choose your model

Where keys go. Paste them into Providers (alt+p) or friday settings, or set them in your environment. <PROVIDER>_MODEL picks a provider's model, and <PROVIDER>_SMALL_MODEL a cheaper one for searching, checking and summaries.

Your Claude plan. With Claude chosen, your own Claude Code does the work, billed to your plan. Friday streams its replies, puts its permission questions in Friday's approval dialog, and keeps the conversation if you switch models. Friday never sees your Claude or ChatGPT account.

How a request runs

1. It looks first. Friday reads and searches the project, often with helpers exploring several places at once.
2. It plans the work as a checklist you can see (/todos).
3. It writes the tests first, runs them, and sees them fail for the right reason.
4. It changes the code, asking before each edit or command your mode does not allow on its own. Every tool call shows in the chat as it happens, with its result.
5. It proves the change works by running the tests, then the project's own checks. A build alone is not enough.
6. It suggests what is next: up to three next steps, each with why. alt+1, alt+2 or alt+3 puts one in the input.

You can type at any point: what you send reaches Friday at its next step. esc stops the turn.

Modes: how much it may do alone

shift+tab cycles through them, and --plan, --auto or --defender starts in one. Read-only commands such as git status, ls or rg never ask, in any mode.

Helpers: several agents at once

Friday splits work between helpers (sub-agents) and uses them on its own when a task calls for it:

• explore searches several parts of the project at the same time;
• plan designs an approach before anything changes;
• review reads a change with fresh eyes;
• verify runs the checks and reports what passed;
• general does a whole piece of work.

A helper can run in the background while Friday carries on. One that edits in the background works on its own git branch, so it never edits a file under Friday, and its report says how to take its work. /subagents shows what each is doing. Write your own in .archymedes/agents/<name>.md (see writing a role).

The interface

friday opens a small desktop in the terminal. Everything works with the keyboard and the mouse.

• One way to move. A click selects and a second click opens. The arrows move, enter opens, and esc steps back out to the bars. The wheel scrolls whatever is under the pointer.
• Finder. alt+g shows everything Friday can open as icons: apps, commands, sessions, files, themes. Type to search all of them.
• Start menu. ctrl+space finds any app, action, session or file by name.
• Comment on a diff. In Changes, [ and ] pick a line and c writes a note on it. Your notes go with your next message, each with its file, line and code.
• Suggestions while you type. The row above the input offers the command, earlier request or file you seem headed for; tab takes it. ARCHYMEDES_SUGGEST=off turns suggestions off.
• Make it look like yours. /theme and /wallpaper show previews as you move through them. alt+w replays the first-run walkthrough.

Commands

Type / in a session to see them all. The ones you will use most:

| /undo, /rewind, /diff | take back the last turn (files, conversation or both), go back to any turn, see what changed | | /btw <question> | a side question, even while Friday works; the answer stays out of the conversation | | /cost, /subagents | tokens used, by the conversation and by each helper | | /skills, /mcp, /hooks, /lsp | what Friday found for this project | | /profile [name], /vim | another set of keys and settings; vim keys in the input |

/review, /fork, /goal, /context and /memory still need the earlier TypeScript engine. A command that is not available says so, and how to get it.

What keeps your code safe

• You approve changes. An approval can be for this once, for this exact action from now on, or for a safe pattern such as a command prefix or a folder.
• Risky actions always stop. Even in auto mode, Friday asks before anything touching credentials, deploys, publishing, pushes or privileged commands. Some commands are refused outright: rm -rf, git reset --hard, mkfs.
• It never overwrites what it has not seen. A file that changed since Friday read it is read again before it is edited.
• Your own rules. .archymedes/rules.json says which commands to allow, always ask, or forbid, by their first words. Each rule can carry examples, checked when it loads, so a rule that does not do what you meant is reported:

{ "rules": [
  { "prefix": ["rm", ["-rf", "-fr"]], "decision": "forbid", "reason": "Use trash-put instead.", "match": ["rm -rf build"] },
  { "prefix": ["git", "push"], "decision": "ask", "not_match": ["git pull"] },
  { "prefix": ["npm", ["test", "run"]], "decision": "allow" }
] }

• Undo. Friday snapshots the project before every turn (in a git repository), and /undo puts the files back, created files removed and deleted ones restored. Your own staged changes are left alone.
• Your hooks. Commands of yours that run before and after each action can stop one, in the same format as Claude Code's.

Friday guards your code. The machine the agent runs on is a separate question: Argus, from the same team, watches that machine, keeps the evidence locally and says what it could not see. It is free for Linux servers, and the desktop edition for Windows + WSL2 is in a free beta: archymedes.xyz/en/solutions/argus.

Make it yours

Everything lives under .archymedes/ in the project, so it travels with the repository.

| .agents/skills/<name>/SKILL.md (or .claude/skills/) | a skill: instructions Friday loads when a task needs them | | .mcp.json (or .archymedes/mcp.json) | MCP servers; their tools cost no context until one is needed | | .claude/settings.json or .archymedes/hooks.json | hooks, in Claude Code's format |

Files other agents read work here as they are: AGENTS.md, Claude Code's skills, MCP servers and hooks. Friday also notifies you when a turn ends or it waits for you while you look elsewhere, sends pictures named in a request, and adds a language server's errors to each edit (gopls, pyright, typescript-language-server, rust-analyzer, clangd, when installed).

Scripts and editors

In an editor. friday acp speaks the Agent Client Protocol on stdio. In Zed's settings:

{ "agent_servers": { "Friday": { "command": "friday", "args": ["acp"] } } }

In scripts. Friday runs without the interface and prints results:

friday --print "add a health check"  one request; the answer on stdout, progress on stderr
friday --json "add a health check"   the same, as JSON lines for another program
echo "add a health check" | friday   a request from a pipe
friday --provider groq --model openai/gpt-oss-120b
friday settings                      keys, models, preferences
friday history                       earlier sessions
friday doctor                        what is wrong with your setup, if anything
friday update                        install the newest Friday
friday login | logout                link this computer to your Friday account, or unlink it

Questions

Which engine runs my session? Friday's engine is written in Go and runs inside the friday binary. A session that needs something only the earlier TypeScript engine has (Codex, for one) runs there on its own. Settings → Engine chooses one for every session.

Can I use it without paying for a model? Yes: friday --free with a free OpenRouter key uses free models only and never falls back to a paid one. Ollama runs models on your own computer.

Something is not working. friday doctor says what is wrong with your setup. The user guide covers the rest.

Where is the full documentation? The engine, the user guide, configuration, tools, helpers and editors.

Requirements

• Linux, macOS or Windows, on x64 or arm64. The friday binary comes with the package.
• Node 22.5 or newer, for settings, --json and sessions on the TypeScript engine.
• Optional: git for Changes, background helpers and worktrees; gh for /pr; ripgrep for faster search; Claude Code or Codex to use those plans.

Apache-2.0 licensed. Source: github.com/chrisnkuno/archymedes-cli.