How imece works

The pieces

Every team member's machine runs a desktop app, a local background service (the daemon) and a local database. The team syncs through imece's servers.

If the servers can't be reached, imece keeps working on your machine. The records you write are queued and go to the team once the connection is back; until then the team's new records don't reach you. When the connection returns, imece tries to pick up what you missed; the desktop app shows how many events it couldn't get.

• Desktop app: shows the team channel, DMs, To-dos, Code and Sessions screens and sends notifications. The local daemon serves its interface.
• Daemon: a local service that runs in the background on your machine. It opens the database, talks to the servers and answers Claude Code's hooks. It keeps running when you close the desktop window.
• Database: a local database on each machine. Decisions, notes, handoffs and messages are stored there. The text of your prompt stays on your machine.
• .imece/ folder: imece keeps a readable copy in the project you've selected. The folder doesn't go into git. imece doesn't change your CLAUDE.md.
• Servers: sign-in, the team, member and channel lists, and passing the team's events between machines.

How a decision travels from agent to agent

Example: Ayşe's agent makes a decision and Mert's agent sees it while it works. This path is set up for Claude Code; for other agents, see Supported agents.

• Recording. Ayşe's agent records the decision. The agent decides when to record; it may not.
• Local write. The record is written to the database on your machine first. If the daemon isn't running at that moment, the record is still saved; the daemon processes it when it starts.
• Spreading. The daemon sends the record to the servers, which pass it to the team's other machines. Personal records are not sent to the team.
• Delivery. In Claude Code, imece adds the team's relevant records to the agent's context while it works (via hooks). If there is nothing to add, nothing is added.
• Text written by your teammates reaches the agent marked as data, not as instructions.
• Chat messages and DMs aren't added to the agent's context.

What an agent records and searches

imece's MCP server gives the agent tools for the team. They work only on a machine that has joined a team. The agent decides when to use them.

What an agent can record:

• Decisions it made.
• Work it finished.
• Lessons it learned.
• Approaches tried and dropped.
• Work left unfinished.
• A handoff to another role.
• The agent can also search the team's records. It reads the chat history only when you allow it: press “Allow reading · 5 min” on the chat screen and the permission lasts for a limited time. DMs can't be searched.

Supported agents

imece gives an agent two things: MCP tools, and in Claude Code, hooks. Hooks are installed only for Claude Code, so records are added to the agent's context automatically only in Claude Code.

• Claude Code: when you connect Claude Code from the Help panel in the desktop app, or pick it while joining a team, imece adds its own hooks and MCP server to Claude Code's settings. It leaves other tools' entries alone. When you uninstall imece, only imece's entries are removed.
• Claude Code hooks are installed at the user level: they run in every Claude Code session on this machine and return empty in a project you haven't selected for imece. A session opened before the setup sees the new entries after it restarts.
• Codex and Cursor: you start them in the desktop app with New session in the Sessions section; imece hands the MCP server to the session itself. The agent runs on your own sign-in. Cursor CLI or Codex (for Codex, also the codex-acp adapter) must be installed and signed in on this computer; imece doesn't bundle them and shows the install command when one is missing.
• imece's hooks don't run in Codex and Cursor sessions. Records aren't added to these agents' prompts automatically; the agent reaches them when it searches the team's records.
• Other MCP-capable CLIs: the “Connect your agent” section of the Help panel gives a ready-made setting. It is an entry named imece under mcpServers: command is imece's path and args is just mcp. You add it to your agent's MCP settings. These agents use only the MCP tools; records aren't added to the prompt automatically. imece works out the project from the git repo in the folder where the MCP server starts.

Handoffs

An agent sends a handoff, or you send one in the desktop app with “Convert to handoff”. A handoff goes to a role, not a person: everyone holding the role sees it and the first to claim the work takes it. The outcome goes back to the sender.

If you send it to a role the team doesn't have, an error comes back and lists the valid roles. If no active member holds the role, the handoff is recorded and the team sees it, but nobody is assigned; the sender is told right away. A handoff nobody claims goes stale (stale) after a while but can still be claimed.

• In the desktop app: the handoff lands in the To-dos list when it arrives, and a notification comes. You claim and close it there.
• In Claude Code: once the handoff reaches the machine, it is added to the agent's context. The description of the work and the reason come together.
• In Codex, Cursor and other MCP agents: the agent sees the waiting handoffs when it searches the team's records.
• The sender sees the outcome: when the recipient closes or rejects the handoff, its state and any result text reach the sender.

Teammates who don't use an AI tool

You can join a team without an agent: choose “I don't use an agent” when you join. From the desktop app you can do the following.

• Write in the team channel and project channels, mention a person or a role (@), open a new channel.
• DMs: write to a teammate directly. A DM goes only to the two participants.
• Send a message to a role with “Convert to handoff”. The member holding the role sees the handoff in To-dos; the agent of a member who uses one sees it in its own context too.
• In To-dos, claim and close the handoffs sent to you.
• In the Team panel, see which project and branch the members who use Claude Code are working on.

Conflict warning

The Code section of the desktop app compares the files you changed with your teammates' branches. The comparison runs on your machine, with git. The Code section works for projects whose repo is mapped on this machine.

The warning informs you; it doesn't block a branch, a commit or a merge.

What a teammate is working on (project, branch name and topic) is announced to the team. The announcement exists only for members working in Claude Code; no warning comes for a member who has no announcement.

• File level: if the files your branch has changed since the base branch (for example main), plus the files you haven't committed, overlap with the files changed on a branch your teammate has pushed, the shared files are listed.
• For the file-level comparison, your teammate's branch must exist on the remote and be visible on your machine. The Refresh button in the Code section runs git fetch --prune origin.
• The warning appears in the Code section and on the person's card in the Team panel. It updates when an agent turn ends, when you press Refresh or when the team's state changes.
• The Code section also checks for things like a half-finished rebase or merge, being behind the base branch and a migration with the same number on another branch.

When something doesn't arrive

If a record or handoff doesn't reach the agent's context, check the following. When a tool call fails, the error message also tells the agent what to do.

imece is a coordination signal, not a lock. A block in the agent's context doesn't mean the agent will act on it. On a prompt about something unrelated, the agent may not mention a waiting handoff; the handoff stays in To-dos. Records can also go stale, and imece flags only some of them.

• A Claude Code session was opened before the setup: restart Claude Code. Hooks and the MCP entry take effect in new sessions.
• The project isn't selected on this machine: the hook returns empty and the tools that write records return a PROJECT_NOT_SELECTED error. Select the project with Connect project in the desktop app, then restart Claude Code; the MCP server checks whether the project is selected at the start of the session.
• This machine hasn't joined a team: the tools return a NOT_JOINED error.
• The local database can't be opened: the tools return a NO_DATABASE error. The hook and the MCP server stay up, and the agent's work goes on.
• The imece service (daemon) isn't running or is slow: the hook returns empty and the agent carries on without waiting. The desktop app starts the service.
• The servers can't be reached: the records you write are queued and go to the team once the connection is back. Until then the team's new records don't reach you.

Security and data

We explain which data is stored where on the Security and data page.

Security and data