Skip to main content

Documentation Index

Fetch the complete documentation index at: https://ade-app.dev/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
Managing Context

Every chat session has a context window — the amount of conversation history and injected context the model can hold at once. ADE shows the context fill level as a meter in the chat header.
When the context meter reaches 70%, ADE suggests compaction. If auto-compaction is enabled (configured in Settings → Chat → Auto-compact threshold), ADE compacts automatically without prompting.Compaction summarizes older messages while preserving:
  • Key decisions made in the session
  • File paths and code blocks from recent turns
  • Current task state and open questions
  • Tool call results from the last few turns
Compaction is lossy by design — exact wording of older messages is not preserved. If there is something in the conversation you want the agent to remember verbatim (e.g., a specific constraint), call it out explicitly before compacting: “Remember: the API must remain backwards compatible with v1 clients.”

​
Project orientation

ADE does not generate PRD or architecture summary files for chat. Agents are instructed to inspect the repository directly when they need project context: start with AGENTS.md, README.md, docs/, package manifests, and the source files relevant to the lane.

​
Working with Artifacts

At the end of a session (or mid-session when the agent produces notable outputs), artifacts are surfaced for your review.

​
Artifact types produced in chat

ArtifactWhen it appears
File changesAfter any file write tool call
ProofsWhen the agent calls ade proof capture or ade proof record (screenshots and short recordings)
Ingested evidenceWhen the agent calls ade proof ingest with external traces or logs
PR linksAfter a PR is created
Test reportsAfter test runner tool calls
NotesWhen the agent explicitly attaches a note

​
What you can do with artifacts

1

Keep — attach to lane pack

Promotes the artifact into the lane’s persistent context. Future chat sessions and missions will have access to it via context injection.
2

Attach to Mission / PR / Linear issue

Links the artifact to an existing Mission, opens it for attachment to a PR description, or creates a Linear issue attachment.
3

Download

Saves the artifact to your local filesystem (useful for screenshots and browser traces).
4

Dismiss

Removes the artifact from the session’s artifact list. It remains accessible in the session’s History entry but is not promoted.

​
Chat History and Sessions

Every chat session is stored with its full transcript, tool call log, timing data, and attached artifacts. Access sessions from the History tab within a Lane view. Each entry shows:
  • Session start time and duration
  • Message count and token total
  • Model used
  • Number of tool calls
  • Artifacts produced
Click any session to open its transcript in read-only view. Click Resume to open a new chat session seeded with the previous session’s summary.

​
Troubleshooting

The agent’s file access is always live — it reads from the filesystem at the time of the tool call. If your changes are not reflected, check:
  1. Are the changes saved? The agent reads saved files, not editor buffers.
  2. Is the agent working in the correct lane? Confirm the lane selector in the chat header.
  3. Ask the agent explicitly: “Re-read src/foo.ts and tell me what you see.”
If the session context is very large (deeply nested tool call results, very long files), compaction may not free enough space. Options:
  • Start a new session — previous context is preserved in History
  • Ask the agent to summarize key decisions and start fresh with that summary
  • Switch to a model with a larger context window in the model selector
Proofs appear in the session artifact panel the moment ade proof finishes. If a proof is missing:
  • Run ade proof list --text in the same lane — if the artifact is listed there, the capture worked and the UI just needs a refresh.
  • Run ade proof status --text to confirm the local capture pipeline is available (on macOS, screencapture must be on PATH and Screen Recording permission granted).
  • Check the chat transcript for the ade proof invocation — the CLI returns an error if the capture failed, and the agent usually surfaces it inline.
See Proof Overview for the full capture workflow.
If ADE tool calls fail consistently:
  1. Run ade doctor --project-root <path> in a terminal to check CLI readiness and see per-domain action counts.
  2. Confirm the desktop socket is being used — ade doctor --json reports whether it is operating in desktop-socket or headless mode.
  3. Check the chat session transcript for the specific tool’s error payload; ADE surfaces the RPC error message inline.
PR creation uses the lane’s current branch. If the agent created a PR on the wrong branch:
  1. Close or update the PR in GitHub directly.
  2. In the chat, tell the agent: “You created the PR on the wrong branch. The correct branch is feature/xyz. Please update or re-create the PR.”
  3. To prevent this in future sessions, use an explicit branch name when asking for a PR: “create a PR from feature/xyz to main.”
This usually indicates the agent is not seeing the tool’s output correctly, or the task goal is ambiguous. Try:
  1. Press Escape to interrupt the current turn.
  2. Clarify the goal: “Stop. The issue is X. I need you to Y instead.”
  3. If the loop continues after clarification, start a new session with a more explicit initial prompt.