Skip to content

feat(session-context): add --skip option for sub-agent session reads #330

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rhuanbarreto merged 2 commits into from
May 23, 2026
Merged

feat(session-context): add --skip option for sub-agent session reads #330

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9a26462
feat(session-context): add --skip option for sub-agent session reads
rhuanbarreto May 22, 2026
80c30a7
docs: regenerate llms-full.txt
rhuanbarreto May 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 25 additions & 15 deletions docs/public/llms-full.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4128,9 +4128,10 @@ Read the Claude Code session transcript for the project.
archgate session-context claude-code [options]
```

| Option | Description |
| ------------------- | ---------------------------------------- |
| `--max-entries <n>` | Maximum entries to return (default: 200) |
| Option | Description |
| ------------------- | ------------------------------------------------------------------ |
| `--max-entries <n>` | Maximum entries to return (default: 200) |
| `--skip <n>` | Skip the N most recent sessions (useful when running as sub-agent) |

### archgate session-context copilot

Expand All @@ -4140,10 +4141,11 @@ Read the Copilot CLI session transcript for the project. Sessions are matched by
archgate session-context copilot [options]
```

| Option | Description |
| ------------------- | ---------------------------------------- |
| `--max-entries <n>` | Maximum entries to return (default: 200) |
| `--session-id <id>` | Specific session UUID to read |
| Option | Description |
| ------------------- | ------------------------------------------------------------------ |
| `--max-entries <n>` | Maximum entries to return (default: 200) |
| `--skip <n>` | Skip the N most recent sessions (useful when running as sub-agent) |
| `--session-id <id>` | Specific session UUID to read |

### archgate session-context cursor

Expand All @@ -4153,10 +4155,11 @@ Read the Cursor agent session transcript for the project.
archgate session-context cursor [options]
```

| Option | Description |
| ------------------- | ---------------------------------------- |
| `--max-entries <n>` | Maximum entries to return (default: 200) |
| `--session-id <id>` | Specific session UUID to read |
| Option | Description |
| ------------------- | ------------------------------------------------------------------ |
| `--max-entries <n>` | Maximum entries to return (default: 200) |
| `--skip <n>` | Skip the N most recent sessions (useful when running as sub-agent) |
| `--session-id <id>` | Specific session UUID to read |

### archgate session-context opencode

Expand All @@ -4166,10 +4169,11 @@ Read the opencode session transcript for the project. Sessions are matched by th
archgate session-context opencode [options]
```

| Option | Description |
| ------------------- | ---------------------------------------- |
| `--max-entries <n>` | Maximum entries to return (default: 200) |
| `--session-id <id>` | Specific session ID to read |
| Option | Description |
| ------------------- | ------------------------------------------------------------------ |
| `--max-entries <n>` | Maximum entries to return (default: 200) |
| `--skip <n>` | Skip the N most recent sessions (useful when running as sub-agent) |
| `--session-id <id>` | Specific session ID to read |

## Examples

Expand Down Expand Up @@ -4197,6 +4201,12 @@ Read the latest opencode session:
archgate session-context opencode
```

Read the parent session (skip the sub-agent's own session):

```bash
archgate session-context claude-code --skip 1
```

---

## Reference: archgate telemetry
Expand Down
40 changes: 25 additions & 15 deletions docs/src/content/docs/pt-br/reference/cli/session-context.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,9 +19,10 @@ Lê a transcrição de sessão do Claude Code para o projeto.
archgate session-context claude-code [options]
```

| Opção | Descrição |
| ------------------- | ------------------------------------------- |
| `--max-entries <n>` | Máximo de entradas a retornar (padrão: 200) |
| Opção | Descrição |
| ------------------- | ------------------------------------------------------------------- |
| `--max-entries <n>` | Máximo de entradas a retornar (padrão: 200) |
| `--skip <n>` | Pular as N sessões mais recentes (útil ao executar como sub-agente) |

### archgate session-context copilot

Expand All @@ -31,10 +32,11 @@ Lê a transcrição de sessão do Copilot CLI para o projeto. Sessões são corr
archgate session-context copilot [options]
```

| Opção | Descrição |
| ------------------- | ------------------------------------------- |
| `--max-entries <n>` | Máximo de entradas a retornar (padrão: 200) |
| `--session-id <id>` | UUID específico da sessão a ser lida |
| Opção | Descrição |
| ------------------- | ------------------------------------------------------------------- |
| `--max-entries <n>` | Máximo de entradas a retornar (padrão: 200) |
| `--skip <n>` | Pular as N sessões mais recentes (útil ao executar como sub-agente) |
| `--session-id <id>` | UUID específico da sessão a ser lida |

### archgate session-context cursor

Expand All @@ -44,10 +46,11 @@ Lê a transcrição de sessão do agente Cursor para o projeto.
archgate session-context cursor [options]
```

| Opção | Descrição |
| ------------------- | ------------------------------------------- |
| `--max-entries <n>` | Máximo de entradas a retornar (padrão: 200) |
| `--session-id <id>` | UUID específico da sessão a ser lida |
| Opção | Descrição |
| ------------------- | ------------------------------------------------------------------- |
| `--max-entries <n>` | Máximo de entradas a retornar (padrão: 200) |
| `--skip <n>` | Pular as N sessões mais recentes (útil ao executar como sub-agente) |
| `--session-id <id>` | UUID específico da sessão a ser lida |

### archgate session-context opencode

Expand All @@ -57,10 +60,11 @@ Lê a transcrição de sessão do opencode para o projeto. Sessões são corresp
archgate session-context opencode [options]
```

| Opção | Descrição |
| ------------------- | ------------------------------------------- |
| `--max-entries <n>` | Máximo de entradas a retornar (padrão: 200) |
| `--session-id <id>` | ID específico da sessão a ser lida |
| Opção | Descrição |
| ------------------- | ------------------------------------------------------------------- |
| `--max-entries <n>` | Máximo de entradas a retornar (padrão: 200) |
| `--skip <n>` | Pular as N sessões mais recentes (útil ao executar como sub-agente) |
| `--session-id <id>` | ID específico da sessão a ser lida |

## Exemplos

Expand All @@ -87,3 +91,9 @@ Ler a última sessão do opencode:
```bash
archgate session-context opencode
```

Ler a sessão pai (pular a sessão do sub-agente):

```bash
archgate session-context claude-code --skip 1
```
40 changes: 25 additions & 15 deletions docs/src/content/docs/reference/cli/session-context.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,9 +19,10 @@ Read the Claude Code session transcript for the project.
archgate session-context claude-code [options]
```

| Option | Description |
| ------------------- | ---------------------------------------- |
| `--max-entries <n>` | Maximum entries to return (default: 200) |
| Option | Description |
| ------------------- | ------------------------------------------------------------------ |
| `--max-entries <n>` | Maximum entries to return (default: 200) |
| `--skip <n>` | Skip the N most recent sessions (useful when running as sub-agent) |

### archgate session-context copilot

Expand All @@ -31,10 +32,11 @@ Read the Copilot CLI session transcript for the project. Sessions are matched by
archgate session-context copilot [options]
```

| Option | Description |
| ------------------- | ---------------------------------------- |
| `--max-entries <n>` | Maximum entries to return (default: 200) |
| `--session-id <id>` | Specific session UUID to read |
| Option | Description |
| ------------------- | ------------------------------------------------------------------ |
| `--max-entries <n>` | Maximum entries to return (default: 200) |
| `--skip <n>` | Skip the N most recent sessions (useful when running as sub-agent) |
| `--session-id <id>` | Specific session UUID to read |

### archgate session-context cursor

Expand All @@ -44,10 +46,11 @@ Read the Cursor agent session transcript for the project.
archgate session-context cursor [options]
```

| Option | Description |
| ------------------- | ---------------------------------------- |
| `--max-entries <n>` | Maximum entries to return (default: 200) |
| `--session-id <id>` | Specific session UUID to read |
| Option | Description |
| ------------------- | ------------------------------------------------------------------ |
| `--max-entries <n>` | Maximum entries to return (default: 200) |
| `--skip <n>` | Skip the N most recent sessions (useful when running as sub-agent) |
| `--session-id <id>` | Specific session UUID to read |

### archgate session-context opencode

Expand All @@ -57,10 +60,11 @@ Read the opencode session transcript for the project. Sessions are matched by th
archgate session-context opencode [options]
```

| Option | Description |
| ------------------- | ---------------------------------------- |
| `--max-entries <n>` | Maximum entries to return (default: 200) |
| `--session-id <id>` | Specific session ID to read |
| Option | Description |
| ------------------- | ------------------------------------------------------------------ |
| `--max-entries <n>` | Maximum entries to return (default: 200) |
| `--skip <n>` | Skip the N most recent sessions (useful when running as sub-agent) |
| `--session-id <id>` | Specific session ID to read |

## Examples

Expand All @@ -87,3 +91,9 @@ Read the latest opencode session:
```bash
archgate session-context opencode
```

Read the parent session (skip the sub-agent's own session):

```bash
archgate session-context claude-code --skip 1
```
9 changes: 9 additions & 0 deletions src/commands/session-context/claude-code.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,16 +14,25 @@ const maxEntriesOption = new Option(
"maximum entries to return (default: 200)"
).argParser((val) => parseInt(val, 10));

const skipOption = new Option(
"--skip <n>",
"skip the N most recent sessions (useful when running as a sub-agent)"
)
.argParser((val) => parseInt(val, 10))
.default(0);

export function registerClaudeCodeSessionContextCommand(parent: Command) {
parent
.command("claude-code")
.description("Read Claude Code session transcript for the project")
.addOption(maxEntriesOption)
.addOption(skipOption)
.action(async (opts) => {
try {
const projectRoot = findProjectRoot();
const result = await readClaudeCodeSession(projectRoot, {
maxEntries: opts.maxEntries,
skip: opts.skip,
});

if (!result.ok) {
Expand Down
9 changes: 9 additions & 0 deletions src/commands/session-context/copilot.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,17 +14,26 @@ const maxEntriesOption = new Option(
"maximum entries to return (default: 200)"
).argParser((val) => parseInt(val, 10));

const skipOption = new Option(
"--skip <n>",
"skip the N most recent sessions (useful when running as a sub-agent)"
)
.argParser((val) => parseInt(val, 10))
.default(0);

export function registerCopilotSessionContextCommand(parent: Command) {
parent
.command("copilot")
.description("Read Copilot CLI session transcript for the project")
.addOption(maxEntriesOption)
.addOption(skipOption)
.option("--session-id <id>", "Specific session UUID to read")
.action(async (opts) => {
try {
const projectRoot = findProjectRoot();
const result = await readCopilotSession(projectRoot, {
maxEntries: opts.maxEntries,
skip: opts.skip,
sessionId: opts.sessionId,
});

Expand Down
9 changes: 9 additions & 0 deletions src/commands/session-context/cursor.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,17 +14,26 @@ const maxEntriesOption = new Option(
"maximum entries to return (default: 200)"
).argParser((val) => parseInt(val, 10));

const skipOption = new Option(
"--skip <n>",
"skip the N most recent sessions (useful when running as a sub-agent)"
)
.argParser((val) => parseInt(val, 10))
.default(0);

export function registerCursorSessionContextCommand(parent: Command) {
parent
.command("cursor")
.description("Read Cursor agent session transcript for the project")
.addOption(maxEntriesOption)
.addOption(skipOption)
.option("--session-id <id>", "Specific session UUID to read")
.action(async (opts) => {
try {
const projectRoot = findProjectRoot();
const result = await readCursorSession(projectRoot, {
maxEntries: opts.maxEntries,
skip: opts.skip,
sessionId: opts.sessionId,
});

Expand Down
9 changes: 9 additions & 0 deletions src/commands/session-context/opencode.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,17 +14,26 @@ const maxEntriesOption = new Option(
"maximum entries to return (default: 200)"
).argParser((val) => parseInt(val, 10));

const skipOption = new Option(
"--skip <n>",
"skip the N most recent sessions (useful when running as a sub-agent)"
)
.argParser((val) => parseInt(val, 10))
.default(0);

export function registerOpencodeSessionContextCommand(parent: Command) {
parent
.command("opencode")
.description("Read opencode session transcript for the project")
.addOption(maxEntriesOption)
.addOption(skipOption)
.option("--session-id <id>", "Specific session ID to read")
.action(async (opts) => {
try {
const projectRoot = findProjectRoot();
const result = await readOpencodeSession(projectRoot, {
maxEntries: opts.maxEntries,
skip: opts.skip,
sessionId: opts.sessionId,
});

Expand Down
14 changes: 7 additions & 7 deletions src/helpers/session-context-copilot.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,17 +119,17 @@ export async function readCopilotSession(
};
}

// 3. Select session by ID or most recent
// 3. Select session by ID or most recent (with optional skip)
const skip = options?.skip ?? 0;
const target = options?.sessionId
? matching.find((s) => s.name === options.sessionId)
: matching[0];
: matching[skip];

if (!target) {
return {
ok: false,
error: `Session not found: ${options?.sessionId}`,
available: matching.map((s) => s.name),
};
const error = options?.sessionId
? `Session not found: ${options.sessionId}`
: `Only ${String(matching.length)} session(s) available but --skip ${String(skip)} requested`;
return { ok: false, error, available: matching.map((s) => s.name) };
}

// 4. Read events.jsonl
Expand Down
14 changes: 7 additions & 7 deletions src/helpers/session-context-opencode.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -105,17 +105,17 @@ export function readOpencodeSession(
};
}

// 3. Select session by ID or most recent
// 3. Select session by ID or most recent (with optional skip)
const skip = options?.skip ?? 0;
const target = options?.sessionId
? matching.find((s) => s.id === options.sessionId)
: matching[0];
: matching[skip];

if (!target) {
return {
ok: false,
error: `Session not found: ${options?.sessionId}`,
available: matching.map((s) => s.id),
};
const error = options?.sessionId
? `Session not found: ${options.sessionId}`
: `Only ${String(matching.length)} session(s) available but --skip ${String(skip)} requested`;
return { ok: false, error, available: matching.map((s) => s.id) };
}

// 4. Read messages for the session
Expand Down
Loading
Loading