# The home screen

> One machine, one folder, and a row of seven tiles. Everything you see is scoped to the folder in the header, and moving folder moves the lot.

Open a machine and this is where you land: the folder you are working in, the
chats in it, and a row of seven tiles.

![the home screen — the machine, the folder, and the seven tiles](https://beafk.app/docs-shots/home.webp)

## A project is a folder

A project is a folder on your machine, usually a git repository. The header
names the one you are in. Tap it to move — browse the machine, pick a repository
it already knows, or point at a path.

Everything follows the folder: the chats you see, the commands on the
tiles, the variables that get delivered, the git screen, the roles a crew can
use.

You can have several going. Chats in different folders run at the same
time on the same machine — only what you are *looking* at is per-folder.

The header is one folder because a screen has to be about something. **A chat is
not** — it runs in one folder and can carry up to eight, which is how a job that
spans two checkouts gets done. See
[more than one folder](https://beafk.app/docs/a-chat.md#more-than-one-folder).

### Getting your code onto the machine

However you normally would — `git clone` over `ssh`, or ask an agent to do it
("clone this repository into ~/projects"). If the repository is private, the
machine needs a credential of its own; [git](https://beafk.app/docs/git.md) says what that is.

### Deeper folders win

One rule runs through everything scoped to a folder —
[variables](https://beafk.app/docs/variables.md), [tool servers](https://beafk.app/docs/tool-servers.md),
[skills](https://beafk.app/docs/skills.md), [roles](https://beafk.app/docs/writing-a-role.md): a setting on a folder
reaches everything under it, and a deeper folder's own setting beats it. What
that buys in a monorepo is worked through on [variables](https://beafk.app/docs/variables.md).

## The seven tiles

- **commands** — the lines this project is run by, as buttons. See
  [commands](https://beafk.app/docs/commands.md).
- **tasks** — a small work list, and the chats doing each item. See
  [tasks](https://beafk.app/docs/tasks.md).
- **git** — every branch, the diff, the graph, and a chat that works them. See
  [git](https://beafk.app/docs/git.md).
- **system** — what this machine is doing right now, and what the agents are
  costing it. See [is the machine all right?](https://beafk.app/docs/is-the-machine-all-right.md).
- **logs** — everything the machine said, and what took how long. See
  [logs and timings](https://beafk.app/docs/logs.md).
- **usage** — what the agents on this machine spent, by model. See
  [usage](https://beafk.app/docs/usage.md).
- **settings** — the agents, tool servers, skills, variables and this panel's
  own behaviour. See [settings](https://beafk.app/docs/settings.md).

Two screens are not tiles: the [trash](https://beafk.app/docs/the-trash.md) and the
[board of who is holding which files](https://beafk.app/docs/holding-files.md). Both are reached
from settings, at the moment the question comes up.

## The chats

Under the tiles are the threads in this folder, most recent first. The ones that
are working are marked as working, and the ones that finished while you were
away are marked as unread.

Tap one to open it. Tap **new** to start another — as many as you like, on as
many agents as you like, at once. See [a chat](https://beafk.app/docs/a-chat.md).

When an agent is the wrong tool, run a line yourself and watch it:
[running a line yourself](https://beafk.app/docs/the-terminal.md).

## The sidebar

The rail on the left — a drawer on a phone — is every chat on this machine,
most recent first. It is how you get from one project to another without going
home first.

![behind ☰, every chat on this machine, most recent first — the grouping sits next to search](https://beafk.app/docs-shots/folders.webp)

**Group chats**, next to search, cuts that list four ways:

- **all** — every chat on this machine, most recent first. This is how it
  opens.
- **merged** — the folders you are in, as one list.
- **by folder** — a heading per directory.
- **by project** — the folders a project spans, under its name.

![Group chats — all, merged, by folder, by project](https://beafk.app/docs-shots/groups.webp)

**all** hides nothing. The other three only regroup the folders already on
screen; a tap at the foot of the list reaches the rest of the machine.

## Where beafk keeps its own things

`~/.beafk` on the machine — its database, its key, the variables it delivers.

Your project folders are yours. beafk writes into one only where you have asked
it to, and there are exactly two things it ever writes: an `.env` you turned on,
and the `.gitignore` line that keeps it out of the repository. The rules around
that are in [variables](https://beafk.app/docs/variables.md).

## Everything is one machine

This screen is one machine. Your other machines are on the fleet screen in beafk
cloud, and each has a panel of its own. No screen mixes two machines'
chats — they are different computers, with different files.

---

beafk documentation · The panel · https://beafk.app/docs/the-home-screen

In this section:
- The home screen — https://beafk.app/docs/the-home-screen.md (this page)
- Settings — https://beafk.app/docs/settings.md
- Pictures, both ways — https://beafk.app/docs/pictures-both-ways.md
- Seeing it before it is built — https://beafk.app/docs/seeing-it-before-it-is-built.md
- Running a line yourself — https://beafk.app/docs/the-terminal.md
- The keys a phone does not have — https://beafk.app/docs/keys-a-phone-does-not-have.md

Every page, one line each: https://beafk.app/docs/llms.txt
All of it in one file: https://beafk.app/docs/llms-full.txt