Friday

Friday is a minimal local AI harness agent for developers and agent builders. It provides a small friday CLI/TUI that connects to an AI provider, streams chat responses, and stores inspectable local sessions.

The MVP started with the provider/session core first. Friday now has a small read-only workspace tool loop (list_files, read_file, grep) but is still intentionally not a full coding agent: it does not load plugins, edit files, run shell commands, automate browsers, or perform computer-use actions.

What works now

• One-shot terminal chat with streaming output: friday chat "hello"
• Interactive first-party terminal TUI: friday chat from a TTY
• Fixed local config file: ~/.friday/config.json
• OpenAI-compatible provider adapter, including custom baseURL
• Thinking/reasoning stream display for providers that emit OpenAI-compatible reasoning fields
• Local session metadata and append-only JSONL records under ~/.friday/sessions/
• Session list/show/resume commands
• Doctor command for setup checks
• Typed provider, session, event, workspace, and chat engine seams for future extension work
• Read-only workspace tools for provider-requested list_files, read_file, and grep calls
• TUI @file / @folder tags for explicit workspace context
• Tool output cards with compact previews

Requirements

• Node.js 22+
• npm
• An OpenAI-compatible endpoint

Install and build

From the repository root:

npm install
npm run build

Friday is now an npm workspace monorepo. The reusable packages live under packages/, and the CLI/TUI app lives in packages/agent.

Run the built CLI:

node packages/agent/dist/cli/main.js --help

During development you can use:

npm run dev -- --help

The CLI app package is scoped because the unscoped friday package name is already taken. Install @friday-night/agent while using the executable binary name friday:

npm install -g @friday-night/agent
friday --help

Configuration

Friday reads its config from one fixed file:

~/.friday/config.json

The CLI intentionally does not expose a config path override. This keeps Friday predictable for humans and agents.

Example for an OpenAI-compatible local endpoint:

{
  "providerId": "openai",
  "modelId": "kimi-k2.6:cloud",
  "providerConfig": {
    "baseURL": "http://localhost:11434/v1",
    "apiKey": "dummy"
  }
}

Create it manually:

mkdir -p ~/.friday
cat > ~/.friday/config.json <<'JSON'
{
  "providerId": "openai",
  "modelId": "kimi-k2.6:cloud",
  "providerConfig": {
    "baseURL": "http://localhost:11434/v1",
    "apiKey": "dummy"
  }
}
JSON

You can also update common fields with CLI commands:

friday config set provider openai
friday config set model kimi-k2.6:cloud
friday config set base-url http://localhost:11434/v1
friday config set api-key dummy

Inspect config:

friday config get
friday config get provider
friday config get model
friday config get base-url
friday config get api-key

friday config get api-key only prints whether a key is set; it does not echo the secret.

API keys

Friday reads the API key only from providerConfig.apiKey in ~/.friday/config.json.

For local OpenAI-compatible servers that ignore auth, use a dummy key:

"apiKey": "dummy"

For hosted OpenAI, put the real API key in providerConfig.apiKey.

Local data

Friday stores sessions under the fixed local directory:

~/.friday/sessions/<sessionId>/
  session.json
  records.jsonl

See docs/session-format.md for details.

Chat

One-shot chat:

friday chat "hello"

Resume an existing session:

friday chat "continue" --session <sessionId>

Override provider/model for a new session:

friday chat "hello" --provider openai --model kimi-k2.6:cloud

Interactive TUI:

friday chat

The TUI uses a minimal reading layout: the transcript is plain text without an outer frame, the bottom composer is boxed, and the status line shows the current folder, git branch, and model. Type @ in the composer to tag workspace files/folders, then press Tab to complete the selected suggestion. File tags attach bounded file content using Pi-style <file name="...">...</file> context; folder tags attach a bounded tree listing. The TUI requires a TTY. In non-interactive environments, use friday chat <prompt>.

TUI slash commands

While in the TUI, type / to expand inline command suggestions directly inside the composer box.

Current commands:

• /help — Show available commands and shortcuts
• /doctor — Run configuration diagnostics
• /status — Show session, provider, model, and config state
• /clear — Clear visible messages (does not delete session records)
• /config — Show redacted configuration
• /sessions — List recent sessions
• /resume <sessionId> — Switch to a previous session
• /theme [default-dark|ansi|no-color] — Show or change the UI theme
• /quit — Exit the interactive TUI (/exit is an alias)

Friday's slash-command surface is still chat/config/session focused. There are no /tools, /shell, /edit, /permissions, /agent, or custom commands yet. Model-requested read-only workspace tools are enabled underneath the chat turn loop. When a tool finishes, the transcript shows a compact card containing the tool name and a preview of the result output.

Thinking blocks

Some OpenAI-compatible providers stream reasoning in fields such as reasoning_content, reasoning, thinking_content, or thinking. Friday normalizes these as thinking deltas.

In one-shot CLI chat, thinking is shown before the final answer:

<thinking>
...
</thinking>

Final answer text...

In the TUI, thinking appears as a separate gray "Thinking" block. Thinking text is displayed live but is not persisted as assistant answer content in the session context.

Sessions

List sessions:

friday sessions list

Show session metadata:

friday sessions show <sessionId>

Check that a session can be resumed:

friday sessions resume <sessionId>

friday chat --session <sessionId> is the command that actually sends a new message into an existing session.

Doctor

Check setup:

friday doctor

Doctor checks:

• provider configured
• model configured
• provider registered
• API key available from config or environment
• provider local health validation

Development checks

npm run lint          # source policy: kebab-case TS filenames + .ts/.tsx relative imports
npm run format:check  # Biome formatting
npm run typecheck
npm test
npm run build
npm run release:check

Source imports follow the Pi-style policy: TypeScript source uses relative .ts/.tsx imports and each workspace enables rewriteRelativeImportExtensions so emitted JavaScript imports point at .js files. The test suite uses fake providers and does not require network access or real provider credentials.

Public packages and releases

Reusable packages are split under packages/:

packages/ai      # provider adapters
packages/core    # session, workspace, chat engine, provider contracts
packages/tools   # capability/tool registry and built-ins
packages/tui     # reusable terminal UI primitives
packages/agent   # Friday CLI/TUI app and friday binary

See docs/release.md for the release/versioning checklist, package tagging policy, and the deferred CLI npm package decision.

Architecture overview

Runtime modules are split by package:

• @friday-night/ai owns provider adapters such as OpenAIProvider.
• @friday-night/core owns ConfigManager, ProviderRegistry, FileSessionStore, EventBus, workspace context, and ChatEngine.
• @friday-night/tools owns the tool registry/runner and built-in read-only workspace tools.
• @friday-night/tui owns reusable terminal primitives.
• @friday-night/agent wires the packages into the friday CLI/TUI app.

The agent app imports packages instead of duplicating provider/session/tool logic.

See docs/architecture.md for the full architecture.

Extension direction

Friday exposes internal seams that can later support extension work:

• provider registration
• command registration
• UI surfaces
• session lifecycle hooks
• event subscribers
• future write/shell/MCP capability contributions

The MVP documents these seams but does not ship a plugin loader or third-party extension runtime. See docs/extension-seams.md.

Explicit non-goals for the MVP

Friday currently does not provide:

• extension/plugin loading
• shell commands
• file writes as model actions
• browser automation
• computer-use
• code editing or patching
• planning/review/subagent workflows
• cloud sync or team accounts

These boundaries keep the first release focused on a trustworthy provider/session harness with read-only workspace inspection.