Skip to content

Projects ​

A project is a small file that lists where the things for one piece of work live: a source folder, a few notes, a Drive link, a path on another machine. Pin a project to a chat session and the agent sees that list in every turn, so you do not have to say "look here" again.

What you get ​

  • One list per piece of work. Local folders, notes, URLs and paths on remote machines sit side by side in one file.
  • The agent knows what matters. The pinned project's list is part of the system prompt of that session.
  • A working directory per session. A project can name a folder. Relative paths and shell commands of the session then run there.
  • The agent keeps the files. You describe the project in the chat; the agent creates and updates the file with its project tools.
  • Nothing moves. A project only points. Your files stay where they are, and the agent opens them with its normal tools.

Projects are off by default.

Set it up ​

Add a projects: block to ~/.somora/config.yaml:

yaml
projects:
  enabled: true
  entities:
    - slug: privat
      label: Privat
    - slug: acme
      label: acme GmbH

Restart somora:

bash
somora server restart

On Linux systemctl --user restart somora does the same. Then tell the agent about a project:

Make a new project Home cinema under Privat. The source code is in
~/code/home-cinema, the setup notes are in my vault under
Privat/Home cinema/Setup.md. Pin it.

The agent checks the entity with entity_list, creates the file with project_create and pins it with project_focus. From the next turn on it knows the list.

Note

While projects.enabled is false or the block is missing, the feature is invisible: no slash commands, no chip in the chat header, no Project column in the Sessions window, no project tools, and every project route answers 503.

Entities ​

Every project belongs to exactly one entity, for example "Privat" or "acme". You define the entities in config.yaml. Agents cannot add one.

The fixed list protects against misheard names. When dictation turns "acme" into something else, the agent looks at entity_list and picks the closest match. If it tries the wrong slug anyway, project_create refuses with unknown entity '<slug>' — available: privat, acme and the agent tries again.

With enabled: true and an empty entities list, no project can be created. Entities are also a filter: project_list with entity: "privat" returns only those projects.

The project file ​

One file per project, ~/.somora/projects/<slug>.md. The slug is lowercase and matches [a-z0-9_-]+. The file is YAML frontmatter with an empty body:

yaml
---
slug: home-cinema
name: Home cinema
entity: privat
description: Receiver, beamer, acoustic treatment in the living room
color: "#4f46e5"
tags:
  - hardware
  - wip
created: 2026-04-15T10:23:00Z
updated: 2026-05-13T09:42:00Z
expires: null
archived: false
workdir: ~/code/home-cinema
paths:
  - ref: ~/code/home-cinema/
    label: Sourcecode
  - ref: ~/Documents/somora-vault/Privat/Home cinema/Setup.md
    label: Setup notes
  - ref: https://drive.google.com/drive/folders/xyz
    label: Drive folder
  - ref: gpu-box:/home/me/avr-logs/
    label: AVR logs
---

The files are readable and fit under version control. You rarely edit them by hand, because the agent maintains them. Notes about a project belong in a separate Markdown file that the project points to.

Pointers ​

Each entry under paths is a ref and an optional label. The kind of pointer is read from the shape of the ref. No type is stored.

Shape of refKindThe agent opens it with
~/... or /...localfile_read, file_list, file_search
<scheme>://... such as https:// or gdrive://urlweb_fetch, browser tools, a Drive skill if installed
<resource-slug>:/...resourcefile_read or exec with target: "<resource-slug>"

A ref of any other shape is refused. For a resource pointer the part before :/ must be a slug under resources in config.yaml, otherwise the write is refused with the list of known resources. Local paths and URLs are not checked for existence, so a pointer may name a file that does not exist yet.

A pointer without a label is shown with a derived one: the file or folder name, or the host of a URL.

Working directory ​

A project may name its working directory, usually the repository:

yaml
workdir: ~/code/weather-station

The path must be absolute or start with ~/. Pinning such a project makes the folder the session's working directory:

  • Relative paths in file_read, file_write, file_patch, file_search, file_list and analyze_file, and in image or video references, resolve there instead of the agent's workspace.
  • exec runs there unless the call names a cwd.
  • A builder agent shows the folder in its environment block and keeps its plan file there.
  • Sub-agents spawned from the session inherit the pin and the folder.

A folder that does not exist yet is created when the project is pinned, so you can name a new repository before its first file exists. Clearing the pin restores the agent's workspace. Set the folder with project_create, or with project_update and set_field on workdir.

Note

A builder session keeps its pin while a turn runs there. Unpinning or switching is refused until the turn is over.

Pinning a project ​

A session has at most one pinned project. The pin is stored in the session's meta file (<session>.meta.json, fields projectSlug and projectLinkedAt). It survives restarts and model switches.

HowWhereTo clear
/projekt <slug> or /project <slug>TUI and web/projekt unlink
Click the folder button or the chipWeb chat headerUnlink in the popover
The agent calls project_focusDuring a turnproject_focus with slug: null

What happens on a pin:

  1. The session's meta file gets the slug and the time.
  2. A project_switched event is written to the session log, with the old slug, the new slug and who switched (tool or slash_command).
  3. From the next turn on, the project is part of the system prompt.

Pinning the project that is already pinned does nothing.

What the agent sees ​

## Active Project: Home cinema

**Entity:** privat
**Description:** Receiver, beamer, acoustic treatment in the living room
**Tags:** hardware, wip

**Pointers:**
- `[local]` ~/code/home-cinema/ — Sourcecode
- `[local]` ~/Documents/somora-vault/Privat/Home cinema/Setup.md — Setup notes
- `[url]` https://drive.google.com/drive/folders/xyz — Drive folder
- `[resource]` gpu-box:/home/me/avr-logs/ — AVR logs

When the user asks about this project, treat the pointers above as the
canonical list of relevant resources. Use your standard tools (file_read
for [local], web_fetch / browser tools for [url], resource tools for
[resource]) to access them on demand — do not assume their contents from
memory.

An **Expires:** line appears when the project has an expiry, and an **⚠ Archived:** line when it was archived after the pin.

Prompt cache ​

The project block is the last part of the system prompt, after the persona, the skills and the session block. A project switch therefore leaves everything before it cached. Recalled memory changes every turn and travels with the message, not in the system prompt.

On the codex-cli engine a resumed thread also gets the block in front of the user message, so the model sees a new pin at once.

Changing a project ​

Ask the agent: "Add ~/research/atmos-comparison.md to the Home cinema project." It calls project_update with one add_path operation.

project_update takes a list of operations and applies all of them or none:

json
{
  "slug": "home-cinema",
  "ops": [
    { "op": "add_path", "ref": "~/research/atmos.md", "label": "Atmos notes" },
    { "op": "set_field", "field": "description", "value": "Updated wording" },
    { "op": "set_tags", "tags": ["hardware", "wip", "avr"] }
  ]
}
opFieldsEffect
set_fieldfield, valueSets name, description, color, expires or workdir. value: null clears the field. name cannot be cleared.
add_pathref, label (optional)Adds a pointer. Refused when the ref is already listed.
remove_pathrefRemoves the pointer with exactly this ref.
set_tagstagsReplaces all tags.
archivereason (optional)Archives the project.
unarchivenoneRestores it.

Slug and entity cannot be changed. To change one, delete the file and create the project again. Sessions that had it pinned lose the project context.

Archiving and deleting ​

A project you no longer use is archived, not deleted. An archived project:

  • is left out of project_list, the web switcher and the slash command suggestions, unless includeArchived: true is passed,
  • still answers project_get by slug,
  • stays pinned where it was pinned, marked with ⚠ in the TUI chip and the Sessions window.

No tool deletes a project, so an agent cannot wipe the list that ties a session to your work. To delete one, remove the file yourself: rm ~/.somora/projects/<slug>.md.

In the clients ​

TUI ​

Command or elementWhat it does
/projekt <slug>, /project <slug>Pins a project.
/projekt unlink (also off, clear, -)Clears the pin.
/projektShows the pinned project: entity, description, tags, pointers.
/projectsLists all projects with entity, number of paths and tags.
Chip in the header📁 <name> while a project is pinned, with ⚠ if it is archived.
/sessionsRows of sessions with a pin end in 📁 <slug>.

Web ​

ElementWhat it does
Folder button in the chat headerShown while nothing is pinned. Opens the switcher.
Chip in the chat headerThe project's name in its color. Opens the switcher.
SwitcherProjects grouped by entity, a search box, and Unlink for the pinned one.
/projekt, /project in the slash popupSuggests unlink first, then the projects.
Project column in the Sessions windowThe pinned project per session, in its color.

The chip updates right away on every client when a pin is set or cleared by a command, the switcher or a route. A pin the agent sets with project_focus shows up when its turn ends.

Creating and editing happens in the chat, through the agent. The web client only shows and switches. The mobile app has no project controls.

What projects do not do ​

  • No nesting. Entities and projects are flat. Use tags to group across entities.
  • No expiry job. expires is information for you and the agent. Nothing archives a project when the date passes.
  • No rename. The slug is fixed, because sessions refer to it.
  • No Drive client. A Drive link is a plain url pointer. The agent needs a skill or the browser to open it.
  • No color picker. Ask the agent to set color, or edit the file.

Settings ​

yaml
projects:
  enabled: false
  entities: []
SettingDefaultMeaning
projects.enabledfalseMaster switch for tools, commands, routes and UI.
projects.entities[]The entities a project may belong to.
projects.entities[].slugnoneIdentifier, [a-z0-9_-]+. Stored in each project as entity.
projects.entities[].labelnoneDisplay name.

In scripts and tool errors the list is named config.projects.entities.

File fields ​

FieldRequiredTypeNotes
slugyesstring[a-z0-9_-]+, same as the file name.
nameyesstringDisplay name.
entityyesstringOne of the configured entity slugs.
descriptionnostringFree text.
colornostringCSS color, for example #4f46e5.
tagsnostring[]Free words. Default [].
createdyesISO timestampSet on creation.
updatedyesISO timestampSet on every update.
expiresnoISO date or nullInformation only.
archivednobooleanDefault false.
archivedAtnoISO timestampSet by archive.
archiveReasonnostringSet by archive when a reason is given.
pathsnolist of {ref, label?}The pointers. Default [].
workdirnostringWorking directory, absolute or ~/....

Tools ​

All six belong to the projects toolset and exist only while the feature is enabled.

ToolParametersWhat it does
entity_listnoneReturns the configured entities.
project_listentity, tag, includeArchivedLists projects with their fields and the number of paths, not the paths.
project_getslugReturns one project in full.
project_createslug, name, entity, optional description, color, tags, expires, paths, workdirCreates the file. Refused when the slug exists or the entity is unknown.
project_updateslug, opsApplies the operations above.
project_focusslug or nullPins a project to the current session, or clears the pin.

Routes ​

MethodPathPurpose
GET/projects/feature{enabled, entityCount}. Always answers 200.
GET/projects/entitiesThe entities.
GET/projectsLists projects. Query: entity, tag, includeArchived=true.
GET/projects/:slugOne project in full.
POST/projectsCreates a project. slug, name and entity are required.
PATCH/projects/:slugApplies ops, same operations as project_update.
GET/agents/:agent/sessions/:session/projectThe session's pin with the full project.
POST/agents/:agent/sessions/:session/projectSets the pin: {"slug": "<slug>"}. null clears it.
DELETE/agents/:agent/sessions/:session/projectClears the pin.

All routes except /projects/feature answer 503 while the feature is off. A client asks /projects/feature once at start to decide whether to show anything. Setting or clearing a pin over a route sends a project event on the session's stream.

Troubleshooting ​

The agent has no project tools, /projekt is unknown.projects.enabled is false, or somora was not restarted after the change. Clients ask for the feature once at start: reload the web page or restart the TUI.

no entities configured in config.projects.entities. Add at least one entity to config.yaml.

pinned slug '<slug>' but project file is missing on disk. The file was deleted while a session had it pinned. The agent gets no project block, and the server log shows project.focused_but_missing. Clear the pin with /projekt unlink or create the project again.

unknown resource '<slug>' in path .... The part before :/ is not a resource in config.yaml. Add the resource or use a local path.

The working directory is ignored. workdir must be absolute or start with ~/. Another value is skipped, and the log shows project.workdir_not_absolute.

the builder is working in project '<slug>' right now. Stop the builder's turn, then unpin or switch.

See also ​

  • API: request and response bodies of every route
  • Builder: how a builder agent uses the project folder
  • Tools: the file and shell tools that follow the working directory
  • Web client: the chat header and the Sessions window
  • Resources: the remote machines a resource pointer can name