Workspaces

A workspace is a folder on your machine with its own place on Workspaces, and in the sidebar once you pin it. It holds sessions, Files, Source, and Terminal. Workspaces on the same machine can access shared files; creating one is not an isolation or permission boundary.

With trusted-project reading, you can discuss an already-trusted project in Chat before opening a session for changes. Being listed on Workspaces or belonging to a portfolio does not grant that trust; each exact project folder needs its own saved trust decision.

Create a workspace

A new workspace is a folder in ~/Workspace: a new local Git repository, or a clone of an existing GitHub repository. Kin and Apps are kept for the house’s own folders; choose another name.

1. Open Workspaces → New workspace.
2. Enter a Name. It also names the workspace’s folder.
3. To clone a repository, enter its GitHub HTTPS or SSH URL under Repository · optional. You can also use Connections → Repositories… → Bring in as a workspace… to fill the form from a repository. Leave it empty for a new local folder; Space starts its Git history on a main branch.
4. Choose Create workspace.
5. Space opens its first session in Chat. Read Kin’s trust decision for the new workspace before continuing.

A cloned repository keeps its existing remote.

You should see: the workspace on Workspaces and its name above the session. If setup stops, Workspaces keeps the attempt. Resolve the reported problem, then choose Resume workspace and Try this workspace again, which keeps the original choice. The open form keeps the failure beside its controls. If you leave it before a failed operation ends, a notice still explains what happened. A partial clone with retained files needs inspection before it can continue; Space does not clear that folder to try again. You can leave Workspaces while setup runs and return to finish setup.

Find a workspace

Workspaces on the sidebar’s rail shows every workspace as a tile. Beside its title it says how many there are and how many are pinned.

• Pinned comes first, in your sidebar’s order. Drag a tile to move it, or choose its …, then Move up or Move down.
• On their own holds the Home workspace and the folders that are not in a portfolio.
• Each portfolio follows, with Open, Source, Add repositories…, a link to GitHub and its own pin at its head, and its repositories grouped by the folder they are in. On a phone or in a narrow page, Open and Open Source are in the portfolio’s … menu beside its pin instead.

Under a workspace’s name, a tile says only what is unusual: how many sessions are live in it, Local only when its history is on this machine alone, or Folder missing. A workspace with email no conversation has read shows how much beside its name, such as 2 unread. Choose a tile to open its Overview. The pin at its end keeps it in the sidebar; see Pin workspaces to the sidebar. Its …, always at the tile’s end beside the pin, holds New session, Open Source, Open on GitHub, Choose icon… and, for a portfolio’s repository, Remove from its portfolio, which leaves its files where they are.

Type in Find a workspace to narrow every section by name. Counts then say how many of each section are shown, such as 2 of 29 repositories; the pinned total beside the page title still counts all your pins. Press / to start finding from anywhere on the page, and Escape to clear it and restore the totals.

Read the workspace Overview

Choose a tile on Workspaces, a pinned workspace in the sidebar, or Overview among the workspace’s views in the top bar. From another workspace’s Files, Source or Terminal, a pinned workspace opens at that same view instead; choose it again for its Overview. The Overview begins with the workspace’s icon and name, then its pin and New session. Beside the name it says only what is unusual: Portfolio, or Local only when the history is on this machine alone. One line beneath names its folder and where its history is kept, such as “~/Workspace/Garden, its history on GitHub.” GitHub there opens the repository in a new tab. A folder without Git history says so, and the Home workspace, a portfolio and a copy say what they are.

Below the head come its sessions and notes, its copies, the views Kin made there, a portfolio’s repositories and what Kin reads there. Sessions lists Kin’s sessions here, the live ones first, and says how many are live beside its title; Session history…, at the end of that line, opens earlier conversations. In a wide window Sessions and Notes stand beside each other; on a phone they stack. On a portfolio’s Overview, Repositories shows its members as tiles by the folder each is in, as Workspaces does, each with its pin and its …. A workspace kept on GitHub also has Keep in sync, which lets it save and share itself with the people who work in it, and adds History beside Source among its views (Shared workspaces). Refresh Overview in the top bar reads the whole page again.

The sidebar keeps Live and your Pinned workspaces; a pinned portfolio’s drawer holds its members. Live keeps every open conversation separately, under its workspace’s heading, whose drawer remembers your choice and stays open while you are viewing a conversation inside it. A closed heading names its count and strongest state. To find a workspace’s earlier conversations, choose Session history… from its menu, or use Session history beside Live to look across workspaces.

To give a place an icon, choose its icon on the Overview or Choose icon… from a tile’s or a pinned workspace’s menu, or the palette. Search by name, or scroll past the suggestions through every icon, grouped by kind, and choose one. The icons are Phosphor’s, with Tabler’s outline icons for what Phosphor doesn’t have, drawn with the same line. It follows that workspace through the sidebar, its sessions, the top bar and the palette.

A local example project. The overview brings sessions, documents, and local measurements together; it does not run a review automatically.

Where the work stands in Git is left to Source and its view in the top bar. Source among the views carries a dot while changes aren’t kept yet or checkpoints aren’t on GitHub yet, and an amber dot when something needs resolving; hover or focus it to read the line of work and its status, such as main · Changes not kept yet · 2 changed. It shows no dot when nothing is waiting. The comparison with GitHub reflects the last time this machine checked, so choose Check GitHub in Source before relying on it. If joining two lines stopped partway, or files are in conflict, the Overview says so where it begins, with Open Source.

Use New session to start work or choose an existing session to continue it; a session chosen here opens in Chat. Files, Source and Terminal open in this workspace, and the session you’re in floats over them and the Overview alike. Choosing another workspace leaves your browser’s session attachment while Kin can keep working.

If the workspace’s folder is missing, the Overview says so where it begins and names where to put a folder back. New session and Review with Kin wait, with that reason, until the folder returns.

Each live row opens the session across the whole row. Its edge light and caption say whether Kin is working, needs you, or has finished. Finished stays until you open the session. The same state follows it into Live, Home’s Sessions card and the palette. Its End session control remains separate from opening it. The separate pencil control, Rename…, lets you name either a live or recently ended conversation without opening it. See Name a session for saving and retrying a name.

Notes is the workspace’s own notes and tasks: Scratchpad.md and Tasks.md at its root. Home’s Notes use the Home workspace instead of following the last project visited. Write in Notes, or switch to Tasks for the board of cards. Both save as you go and Kin can read them. See Write notes and keep track of tasks.

When Kin has built and shown you something while working here, such as a chart, a comparison or a small tool, it waits under Views on this Overview. Choose one to open it beside the conversation. Keep on Home, the Home icon at its end, keeps it on Home too. The Home workspace’s Overview also holds what Kin showed you in Chat or in an app, each saying where it was made. See Views and custom cards.

Copies

A repository’s Overview lists its Copies: retained places where work can proceed apart from the main folder, including copies Kin gives independent agents (see Work side by side). Each card says what the copy would bring back, such as 2 checkpoints to bring back · 3 changed files, its sessions, and whether the project has newer work.

• Bring back adds the copy’s checkpoints to the project’s line in its main folder. Space shows the files first and brings back exactly what you saw; if anything changed since, it asks you to look again. Changes not yet kept in a checkpoint stay behind: keep one in the copy’s Source first.
• Update copy brings the project’s newer work into the copy, when the project moved on since the copy was made. If both changed the same lines, nothing changes and the card names the files, so the copy’s session can sort them out.
• Discard copy…, in the card’s menu, throws away what the copy holds after asking, and lists anything still open in it.

A copy whose session ends with nothing new in it is removed on its own; one with checkpoints not yet brought back stays, even once they are pushed. A copy’s own Overview and Source say which project it belongs to. Its Source’s places are This folder, This copy and the project, with GitHub beside. Between the copy and the project, Bring back appears while the copy holds work and Update copy while the project has newer work. Push its line puts the copy’s own line on GitHub under its own name, for a pull request, after asking. Bring back is still what brings the work into the main folder, and a pushed copy takes the project’s newer work through its session rather than Update copy. In the project’s own Source, each copy is a line on the map; choose its name to see its card. Session history lists a copy’s ended sessions with the project’s, and reopens one in a fresh copy if its copy is gone.

Bring back and Update copy refuse work that would overwrite ignored local files, such as .env. Move the listed files somewhere safe before trying again. A refusal keeps the files and branch as they were.

If Space says Kin did not answer in time, she may still be finishing the change. Wait a moment and refresh the copies before trying again; a missing reply does not mean nothing changed.

Discard copy also refuses if the copy has ignored files of its own, including a new or edited .env. Move those files somewhere safe outside the copy, choose Refresh Overview and try again. The refusal keeps the copy intact. A discard’s Git rescue snapshot cannot recover ignored files; unchanged setup files carried into the copy and dependency/cache folders keep their cleanup rules.

Working with Kin

Working with Kin, near the end of a workspace’s overview, is a short list of what Kin reads when she works there. Each file’s name opens it in Files.

• Instructions: the workspace’s own AGENTS.md, which goes into every session there. Where there is no AGENTS.md, Kin reads CLAUDE.md instead. Kin does not read instructions in a parent folder when it works here, and the list says so when it finds any. Having no instructions is normal: Kin reads the files as it works. If you find yourself telling her the same thing twice, ask her to keep that as instructions.
• Shared guidelines: shown only when Space finds a CONVENTIONS.md in the workspace or a folder above it. It describes shared ways of working, and Kin reads it when asked to or when the instructions link to it.
• Documents: the introduction and current-progress files that exist here, README.md and STATUS.md, each with a short note on what it is for. Your workspace may use other files.

A file is marked only when something is unusual about it, such as Empty file. Only a file Space could not read warns, beside its name, and Some files could not be checked then says that part of the picture is unknown. Nothing is reported as missing, and these are observations, not a score. Choose Refresh Overview in the top bar to check again after files change.

Review with Kin, beside the section’s title, starts a new conversation with “Review this workspace with me.” The opening message folds its supporting instructions under The brief Space gave Kin; expand it to read them. Where there are no shared guidelines, it asks Kin in plain words whether she has what she needs to work well here: whether she can tell what the workspace is and how to begin, how it would check that work is right, whether any instructions are accurate or repeat what Kin is already told or say more than she needs, and whether a password or key sits where Git would save or share it, naming the file but never the secret. Kin suggests at most three small changes, preferring to correct or remove over adding, or says nothing is needed. Where there are shared guidelines, Kin checks the workspace against them and cites its evidence. Either way, Kin asks before changing anything.

Expand Instruction files and size to see the file Kin reads and its estimated text size. Tokens are small pieces of text Kin reads; these estimates describe file size rather than a session’s actual model usage. Where the instructions record them, Workspace details shows the type of work, its stage and version numbering.

Forward email to a workspace

Where shared mail has been configured for your Space, Overview offers Email to this workspace. Choose Enable email address, then Copy address. Save that address as a contact in your usual mail app and forward selected received or sent correspondence to it, adding a note if useful. You do not need to connect your personal mailbox to Space.

Each saved email has a row on Overview. Select it to open the email beneath that row, with its attachments. Arrival starts no conversation and asks no model to read it. The Email view keeps your forwarding note, quoted messages, tables and named inline images readable. As Kin reads it shows the exact document Kin receives. Shown simplified explains conversion limits; remote images do not load.

The document distinguishes the received forwarding envelope and arrival from possible forwarding notes and quoted correspondence. Quoted boundaries remain explicitly derived; an earlier statement does not take the forwarder’s name or arrival date. Data tables retain numbered rows and columns, with merged-cell origins and covered positions. When a table cannot be represented faithfully, its available cell content remains with a specific warning. Image references stay beside their surrounding words, even without an image description. The document does not reproduce cell shading or read text from screenshots; keep the original for those details.

Open Email actions for Download all, which keeps the document, original email, manifest and attachment files together. Download original email keeps the exact message Space received. Save to workspace… asks you to choose a folder here and exports the files into a new email folder there. After saving, Open saved files takes you to the result. Existing files are never overwritten; if that email folder already exists, choose another destination. Until you export, the saved mail stays outside your project files and Git history.

The bundle’s manifest.json records the delivery and workspace identity, received headers, source and attachment hashes, MIME details, known inline-image relationships and citation labels. Conversion warnings remain inside the document and manifest when you export or attach them. Previously saved messages use the improved representation when read, keeping their original email and attachment bytes unchanged.

Each email’s row also says whether a conversation has read it. Not read yet means no conversation has. Read in names the conversation that read it; choose it to open that conversation. An email counts as read when Kin reads it with the workspace’s mail tools, or when you send a message holding the files Ask Kin about this email gave her. Opening an email yourself doesn’t count, and neither do downloads or other programs. Email saved before Space began keeping track says From before reads were kept until a conversation reads it. The section’s heading says how many are unread. So does the workspace’s row in the sidebar’s Pinned list and its tile on Workspaces, such as 2 unread. A pinned portfolio counts its repositories’ unread email while its drawer is closed.

Native mail tools are available for a workspace whose operator has connected Space’s local mail server to Kin. After you trust that server, Kin can list all saved messages, return later for new arrivals, and read the correspondence, warnings and source details. These reads stay in that exact workspace and cannot send mail, change its address or remove a saved copy.

Kin asks before retrieving temporary files. She can open an individual attachment or the original email with her existing readers, including messages with more than eight attachments. The files stay outside your project and last for that tool connection; after reconnecting she retrieves them again. The complete bundle preserves its manifest and inline-image links. Source hashes and citation labels identify the evidence behind an answer. Mail remains untrusted source material, and your workspace’s custody rules still apply.

Ask Kin about this email puts the document, original email, manifest and up to five extracted attachments in an unsent draft. Read or change the words before sending. Removing a draft attachment discards only that handed copy. For a larger bundle, download it and choose the files you want Kin to receive. The complete handoff keeps the existing eight-file limit. Generated image links point to the copies handed to Kin. Removing a draft file can leave a link to that removed copy; keep the complete bundle when its context matters.

Under Address actions, beside Copy address, Replace address gives the workspace a new address and Disable address stops new arrivals through it, each after confirmation. Saved mail remains. Email actions → Remove email… removes the local copy after a second choice; it does not erase copies in your mail provider, the shared receiver or backups. Anyone who knows the address can send to it, so replace it if it receives unwanted mail. The receiving provider and Kinra’s shared mail service hold the correspondence before it reaches your Space.

If delivery cannot finish, the section reports the problem. Check for mail tries again and says what it found. A moved or replaced workspace folder needs a new address; its path does not transfer old correspondence to the replacement folder.

See where your work is

For a repository, Source shows where the project’s work is and how it moves, in plain words, and gives Git’s own word for each thing as you go. Beside its title it names the line of work you are on, such as On main.

The Source control in the workspace’s view bar also describes the Git state Space last read. Point at it or focus it for words such as Changes not kept yet or Only on this machine; the marks do not require opening the full page. While a workspace page is in view, Space reads its state again every few seconds and right after you save, add, rename or delete a file, so work done in the Terminal or by Kin shows up without leaving the page. These reads happen quietly: the refresh button stays still and Source keeps your place. A failed read removes the header’s old state. Refresh Source reads the repository again, while Check GitHub asks the remote for newer work.

At the top stand three places:

• This folder is the files as they are now, with how many have changed since the last checkpoint, or All kept when nothing has. A checkpoint keeps the whole folder as it was at one moment, with a few words about what changed; Git calls it a commit.
• This machine keeps every checkpoint. It says how many there are and how many aren’t on GitHub yet, or Same as GitHub.
• GitHub shows the project’s address, when this machine last checked it, anything newer there, and Check GitHub, which looks at what GitHub has without changing your files.

The moves stand on the arrows between the places, and only when there is something to do. Keep makes a checkpoint of everything changed in this folder. Push sends this machine’s new checkpoints to GitHub, after showing which. Pull brings GitHub’s newer checkpoints here, when nothing here is in the way. A move with nothing to keep, send or take is not shown, and its arrow stands still: with everything kept and the same as GitHub, only Check GitHub remains. Under each move, Space says what it would do, such as 2 checkpoints to GitHub, or why it waits, such as Keep a first checkpoint first. A checkpoint stays on this machine until you push it. A push confirmation counts every outgoing checkpoint, even when its list shows only some of their messages.

If checkpoint counts or the comparison with GitHub cannot be read, Source says that part is unknown. Push and Pull wait for a fresh comparison; Check GitHub can still look for updates. Choose Refresh Source to read again. A failed refresh labels a retained map as the last successful read, rather than presenting it as current.

Git’s answer to a move appears under the places in Space’s words, with Git’s own output folded beneath it under What Git said, whether the move worked or was refused. Read a refusal and that output before trying the same move again. When this machine and GitHub each have checkpoints the other doesn’t, Push and Pull wait together and Ask Kin to join them writes the request for you; pulling again cannot settle it. With no remote, the moves to GitHub wait and Ask Kin to put it on GitHub offers the same help.

Keep a checkpoint

While this folder has changes, Keep a checkpoint lists the changed files; expand one to see its changes. Enter a few words in Checkpoint message and choose Keep checkpoint. The new checkpoint appears where you are on the map.

The sparkle control inside the message field, Write this message with Kin, asks Kin to draft one line from the working changes. It sends Kin the list of changed files and as much of their differences as fits a bounded request, starts no conversation, and changes no files. Read the draft and edit it before keeping it. If you start typing while Kin is writing, your words are kept. Kin must already have worked in the project once; otherwise Space asks you to start a session there first. Kin writes the draft with your Kinra models, even when your conversations use ChatGPT, so it never draws on a ChatGPT subscription. If your Kinra connection has lapsed, Space asks you to reconnect Kinra in Connections.

In a very large repository, Space may say that the list of changes is incomplete. That does not mean the files left out are unchanged. Choose Refresh Source for another read; if the warning remains, review all changes in the Terminal before relying on this list or keeping a checkpoint. A checkpoint still includes changes this list does not show. Write this message with Kin waits until the change list can be read in full.

Lines of work

Lines of work draws the project’s lines as a map. The main line runs along the top, and other lines begin from it and join it again; the newest checkpoints are at the right-hand end. Each square mark is a checkpoint. The larger one is where you are, and a dashed square beyond it stands for changes not kept yet. A tinted checkpoint isn’t on GitHub yet, and an outlined one is on GitHub but not here yet. A cloud shows how far GitHub has a line, a flag marks a milestone, and a folder marks another folder of this project on this machine, such as one of Kin’s copies. Scroll the map sideways to see earlier checkpoints.

Under the map, What the marks mean unfolds its key. It names each mark, then gives Git’s word for it, such as checkpoint · commit or line of work · branch. Choose an entry to find what it names on the map, with one sentence about it; choose it again, press Escape, or fold the key away, to let go.

Below it, Checkpoints on main lists the line’s checkpoints, newest first, with who kept each and when; Show earlier in the list reaches further back. Show earlier on the map extends the map instead. Choose a line’s name to list its checkpoints instead and see where it began, what it has that main doesn’t, and whether GitHub has it. Choose a checkpoint, in the list or on the map, to read its story: its words, who kept it and when, whether GitHub has it, and the files it changed, each expanding to show its changes. Its Git name stands beside Copy its id. A checkpoint with more milestones than fit in its story says that some could not be listed.

Ask Kin about this checkpoint, Ask Kin to start a line from here and Ask Kin to bring it into main write a request in the message box, beside the page or in a new session in the project. Read it and send it when ready; nothing is sent until you do.

For a folder with no repository, Ask Kin to set it up puts “Make this folder a Git repository.” in a conversation draft. Review and send it when ready; choosing the control alone makes no repository.

A folder inside a repository is ordinary files; Source works at the repository’s own root. If joining two lines stopped partway, Source says so: choose between the versions in the Terminal, choose Ask Kin to finish it, or use Undo the joining after reviewing what will be discarded. Keeping a checkpoint waits while files are in conflict.

For several related repositories, continue with Portfolios.