# Sessions: Multi-turn Workflows

Sessions are Magma's most powerful feature. They allow you to conduct complex, multi-turn conversations with coding agents while maintaining a structured log of the entire exchange.

Unlike single-use prompts, a **Session** evolves over time, capturing both your follow-up questions and the agent's responses.


## 1. Creating a Session

- **Obsidian**: Use `Cmd-Ctrl-S` (QuickAdd: Magma session).
- **CLI**: `magma session.gen "Project Refactor"`

A new session starts in **Initial Mode**, which looks very similar to a standard prompt.

A session document contains:

1. **YAML frontmatter** with `magma_type: Session`.
2. **Table of Contents**: Automatically generated by an Obsidian plugin.
3. **Context and Task sections**: For your initial prompt.
4. **Notes section**: For private annotations.


## 2. The Multi-turn Lifecycle

### Step 1: The Initial Prompt

Write your context and initial task in the respective sections. When ready, click **"Copy last prompt to clipboard"**.

### Step 2: The Agent's Response

Send the prompt to your coding agent (e.g., Claude Code). Once the agent responds, you have two choices:

- **Manual**: Copy the agent's response and paste it into the `## Response` section of your session file.
- **Import**: If configured, use the **Import Response** button (see "Response Import Workflow" below).

### Step 3: Follow-up Prompts

To continue the conversation:

1.  Insert the **Session Continuation** template (`Cmd-Ctrl-C` in Obsidian).
2.  This adds the required technical separators: horizontal rules (`----`) and bold-italic keywords (`***Prompt***` and `***Response***`). These boundaries allow Magma to parse the conversation structure.
3.  Write your next question in the `## Follow-up prompt` section.
4.  Click **"Copy last prompt to clipboard"** again. Magma will intelligently copy *only* the new follow-up.

## 3. The "Response Import" Workflow

Magma can automate the process of bringing AI responses back into your vault. This is particularly effective with agents like **Claude Code**.

### How it works

1.  **Instruction**: When you copy a prompt from a session, Magma can append a "Response Instruction" telling the agent: *"Write your response to this specific file path."*
2.  **Execution**: The agent performs the task and writes its reply to a temporary file in the `.responses/` subdirectory. The file path follows this pattern: `sessions/.responses/<SessionName>.response_<timestamp>.md`
3.  **Import**: You click the **"Import Response"** button in Obsidian (or run `magma import-session`). Magma moves the content from the temp file into your session document (replacing the import button) and deletes the temp file.

### Customizing the Response Instruction

The instruction appended to prompts is defined by an EEx template at `templates/session_response_prompt.md.eex`. You can customize this to fit your preferred agent interaction style.

The following variables are available in the template:

- `@session_name`: The name of the session document.
- `@session_file`: The relative path to the session file.
- `@response_file_path`: The path where the agent should write the response.
- `@timestamp`: The current timestamp used in the response filename.

### Setup for Claude Code

To make this seamless with Claude Code, add the following "respond-in-file rule" to your `CLAUDE.md` file. This instructs Claude to write responses to the specified file path, enabling the automated import:

```markdown
## Respond-in-file Rule

When instructed to apply the respond-in-file rule with a specific file path:

1. **Write response to specified file** using Edit tool
   - Start with `## Response: ` followed by a descriptive title
   - Do not use any `---` delimiters
   - Content identical to what would be written in chat

2. **Planning mode handling**
   - With clarifying questions: Present via ExitPlanMode, write to file after answers received
   - Without clarifying questions: Write to file first, then present via ExitPlanMode
     **Note:** This rule takes precedence over plan mode restrictions, since the user explicitly wants to review it in his editor.

3. **Never output main response in chat** - always use Edit tool

4. **Post-response**: Return to conversation and confirm completion
```

## 4. Response Modes

You can control how Magma handles responses by setting `session_response_mode` generally in `Magma.system.config.md` or overwriting this setting individually in the YAML frontmatter of a session document:

- **`auto` (Default)**: Adds the response instruction only if an "Import" button is present in the document.
- **`enabled`**: Always appends the response instruction.
- **`disabled`**: Never appends the instruction; for fully manual workflows.

### Per-Prompt Flexibility (Auto Mode)

The `auto` mode provides powerful granular control. Since it only triggers the response instruction if an "Import" button exists, you can decide **per prompt** whether you want the agent to write a response file back to your vault. 

Simply delete the button (or the entire `***Response***` section) if you only want the agent to perform a specific action (like a code refactor) without documenting its verbal reply in your session.

### Multiple Response Sections

You can also have multiple response sections under a single prompt. This is particularly useful for "Model Comparison" workflows:

1. Send the same prompt to different LLMs.
2. Create multiple `***Response***` sections.
3. Record each model's answer to see which one performed better or collect different opinions.

## 5. The "Notes" Section

Every session ends with a `***Notes***` separator. This is a private space for your own thoughts, scratchpad code, or reminders. 

**Important**: Content in the Notes section is **never** included when you copy or execute a prompt. It is purely for your internal use.