Missing feature: restore conversation history from transcript is not supported

[alberti42]

When resuming an existing session (either via M-x agent-shell + session picker, or M-x agent-shell-resume-session), the buffer starts empty. The agent correctly retains its context server-side, but there's no way to see what was discussed in the previous session.

This makes the resume UX difficult in practice, even though the session picker shows titles and timestamps, once you're in the resumed buffer you have no way to review what was previously said or verify you're continuing from the right point.

I quickly looked into the code and found:

• I suspect that ACP has no mechanism to fetch previous messages (session/resume does not return them)
• agent-shell already saves transcripts to .agent-shell/transcripts/ as Markdown — but the file name is just a timestamp, and the header contains no session ID, so there is no way to match a transcript to a session on resume
• Claude Code also stores full conversation history locally as JSONL at ~/.claude/projects/<project>/<session-id>.jsonl, keyed by session ID, which could serve as an alternative source

A possible approach: include the session ID in the transcript header (a YAML front matter block would be idiomatic, but adding it to the existing Markdown header is fine too). With that link in place, restoring on resume becomes straightforward: look up the transcript by session ID and load it into the buffer — possibly with older exchanges collapsed by default to keep things clean.

The code already has a comment acknowledging this gap (agent-shell does not support restoring sessions from transcript).

Do you already have plans / ideas how you would like to have it implemented in the future? Do you welcome PR on this or do you prefer to first set the first architecture yourself?

Checklist

• I agree to communicate with the author myself (not AI-generated).
• I've read the README's Filing issues section.
• I'm running the latest versions (fill in below).
  • agent-shell version: v0.50.1
  • acp.el version: 0.11.2
  • ACP package (e.g. claude-agent-acp) version: 0.22.2
  • Agent CLI (e.g. claude, gemini) version: n/a
• [n/a] For requesting new agent support, I'm including a link to the ACP-capable agent or related ACP package.
• [n/a] For issues, I'm including ACP traffic (as per README).

[xenodium]

This makes the resume UX difficult in practice, even though the session picker shows titles and timestamps, once you're in the resumed buffer you have no way to review what was previously said or verify you're continuing from the right point.

https://xenodium.com/agent-shell-0-47-1-updates#session-resume-(experimental)

This is still fairly experimental, but have you tried loading instead of resuming sessions(setq agent-shell-prefer-session-resume nil)?

With that link in place, restoring on resume becomes straightforward: look up the transcript by session ID and load it into the buffer

This would be tricky at the moment as what's saved in the transcript isn't easily deserialized and replayed (the markdown doens't have enough metadata) into the buffer as UI/fragments.

Even loading sessions ((setq agent-shell-prefer-session-resume nil)) instead of resuming isn't something I'm currently advocating mainly due to performance. If you load a really long session, it's kinda slow (it has to iterate over a lot of data and generate agent-shell UI/fragments). If keen to git that a spin, beware it's still fairly alpha.

I'm thinking for the use-case you're suggesting, we can likely find a lightweight middle ground somewhere. For example, when resuming, we can automatically send a message to the agent asking to summarize the last thing that was done. A really simple one would be to show a link to the last transcript. Pressing RET on link would automatically open the transcript so you can review as needed.

[alberti42]

For example, when resuming, we can automatically send a message to the agent asking to summarize the last thing that was done.

Yes, I was thinking something like you suggested. But I was hoping to get the full conversation restored. I also don't want to spend tokens to summarize long conversations. And currently, the conversation picker only shows the last sentence, and it is truncated to too few words. So I would have to open several such conversations before I find what I need.

A pragmatic and potentially simpler solution could be:

• Store the session ID in the Markdown (I think this should be a "must" since it is a great return for a relatively small effort to add one extra line); my preference is using a YAML preamble. I would bet that there are already plenty of scripts and tools capable of scanning a compilation of markdown files and indexing the YAML preamble. It makes it easier if we follow a more widely adopted standard because some code is already written.
• When resuming, provide a link in the chat that, if I click on it, opens the previous conversation in a buffer. This would make me already very happy. It does not have to be polished and display the same look as the original. Just showing the Markdown file.
• When you save the updated conversation, you update the old Markdown file by appending the new part of the conversation.

I am thinking, hopefully, Agent Shell will grow into something huge, and if you get support from the community, one day, perhaps in 1 year, we can replace the solution proposed here with a more integrated, elegant approach. But in the meanwhile, we can already work with it with 99% efficacy.

Let me just add, thank you very much for what you did! And please take what I wrote as suggestions.

[guibor]

I agree, storing the session ID in the markdown would go a very long way and would make it easy for anyone to write simple function to restore sessions as needed

[guibor]

Something like this works (advising the function that creates the transcript file).
Save in a SQL Lite database a mapping from session id to transcript, and using that to reload

@xenodium would an implementation of this sort be interesting to add to the package?

(require 'url-util)
(defcustom mdf/agent-shell-transcript-index-db-file
  (expand-file-name "agent-shell/transcript-index.sqlite3" user-emacs-directory)
  "SQLite database storing agent-shell transcript metadata."
  :type 'file)

(defun mdf/agent-shell--file-uri (path)
  "Return a file URI for PATH."
  (let ((expanded (expand-file-name path)))
    (concat "file://"
            (replace-regexp-in-string "%2F" "/" (url-hexify-string expanded)))))

(defun mdf/agent-shell--sqlite-escape (value)
  "Escape VALUE for inclusion in a single-quoted SQLite string."
  (replace-regexp-in-string "'" "''" (or value "")))

(defun mdf/agent-shell--sqlite-run (sql)
  "Run SQL against the transcript index database."
  (let ((sqlite3 (executable-find "sqlite3"))
        (db-file (expand-file-name mdf/agent-shell-transcript-index-db-file)))
    (unless sqlite3
      (error "sqlite3 executable not found"))
    (make-directory (file-name-directory db-file) t)
    (let* ((sql-file (make-temp-file "agent-shell-transcript-index" nil ".sql"))
           (output-buffer (generate-new-buffer " *agent-shell-sqlite*"))
           (command (format "%s %s < %s 2>&1"
                            (shell-quote-argument sqlite3)
                            (shell-quote-argument db-file)
                            (shell-quote-argument sql-file))))
      (unwind-protect
          (progn
            (with-temp-file sql-file
              (insert sql))
            (let ((status (call-process-shell-command command nil output-buffer)))
              (unless (and (integerp status) (zerop status))
                (error "sqlite3 failed (status %s): %s"
                       status
                       (with-current-buffer output-buffer
                         (buffer-string))))))
        (when (file-exists-p sql-file)
          (delete-file sql-file))
        (when (buffer-live-p output-buffer)
          (kill-buffer output-buffer))))))

(defun mdf/agent-shell--current-session-id ()
  "Return the current agent-shell session id if available."
  (or (and (bound-and-true-p agent-shell--state)
           (map-nested-elt agent-shell--state '(:session :id)))
      (and (bound-and-true-p agent-shell--state)
           (or (map-elt agent-shell--state :resume-session-id)
               (map-elt agent-shell--state :fork-session-id)))))

(defun mdf/agent-shell--current-agent-name ()
  "Return the current agent-shell agent name."
  (or (and (bound-and-true-p agent-shell--state)
           (map-nested-elt agent-shell--state '(:agent-config :mode-line-name)))
      (and (bound-and-true-p agent-shell--state)
           (map-nested-elt agent-shell--state '(:agent-config :buffer-name)))
      "Unknown Agent"))

(defun mdf/agent-shell--index-transcript-file (transcript-file)
  "Insert a new transcript row into the SQLite index."
  (let* ((directory (directory-file-name (expand-file-name (agent-shell-cwd))))
         (session-id (mdf/agent-shell--current-session-id))
         (agent-name (mdf/agent-shell--current-agent-name))
         (transcript-link (mdf/agent-shell--file-uri transcript-file))
         (sql (mapconcat
               #'identity
               (list
                "BEGIN IMMEDIATE;"
                "CREATE TABLE IF NOT EXISTS agent_shell_transcripts ("
                "  directory TEXT NOT NULL,"
                "  session_id TEXT NOT NULL,"
                "  agent TEXT NOT NULL,"
                "  transcript_link TEXT PRIMARY KEY NOT NULL"
                ");"
                (format "INSERT OR IGNORE INTO agent_shell_transcripts (directory, session_id, agent, transcript_link) VALUES ('%s', '%s', '%s', '%s');"
                        (mdf/agent-shell--sqlite-escape directory)
                        (mdf/agent-shell--sqlite-escape session-id)
                        (mdf/agent-shell--sqlite-escape agent-name)
                        (mdf/agent-shell--sqlite-escape transcript-link))
                "COMMIT;")
               "\n")))
    (mdf/agent-shell--sqlite-run sql)))

(defun mdf/agent-shell--index-transcript-on-create (orig-fun &rest args)
  "Index the transcript only when `agent-shell--ensure-transcript-file' creates it."
  (let* ((transcript-file (and (boundp 'agent-shell--transcript-file)
                               agent-shell--transcript-file))
         (existed-before (and transcript-file
                              (file-exists-p transcript-file)))
         (result (apply orig-fun args)))
    (when (and transcript-file
               (not existed-before)
               (file-exists-p transcript-file))
      (condition-case err
          (mdf/agent-shell--index-transcript-file transcript-file)
        (error
         (message "agent-shell transcript index skipped: %S" err))))
    result))

(with-eval-after-load 'agent-shell
  (advice-add 'agent-shell--ensure-transcript-file :around
              #'mdf/agent-shell--index-transcript-on-create)
  (setq agent-shell-permission-responder-function
        #'agent-shell-permission-allow-always))

(defun mdf/agent-shell--sqlite-query (sql)
  "Run SQL against the transcript index and return output lines."
  (let ((sqlite3 (executable-find "sqlite3"))
        (db-file (expand-file-name mdf/agent-shell-transcript-index-db-file)))
    (unless sqlite3
      (error "sqlite3 executable not found"))
    (unless (file-exists-p db-file)
      (error "Transcript index does not exist: %s" db-file))
    (process-lines sqlite3 db-file "-noheader" "-separator" "\t" sql)))

(defun mdf/agent-shell--path-from-file-uri (uri)
  "Decode a file URI URI into a local path."
  (when (and uri (not (string-empty-p uri)))
    (url-unhex-string (replace-regexp-in-string "\\`file://" "" uri))))

(defun mdf/agent-shell--collapse-whitespace (text)
  "Collapse whitespace in TEXT to single spaces."
  (string-trim (replace-regexp-in-string "[[:space:]]+" " " (or text ""))))

(defun mdf/agent-shell--transcript-file-contents (path)
  "Return the contents of PATH as a string."
  (with-temp-buffer
    (insert-file-contents path)
    (buffer-string)))

(defun mdf/agent-shell--shorten-string (text width)
  "Return TEXT truncated to WIDTH characters."
  (if (<= (length text) width)
      text
    (concat (substring text 0 (max 0 (- width 3))) "...")))

(defun mdf/agent-shell--transcript-last-user-summary (content)
  "Return a short summary from the last user block in CONTENT."
  (with-temp-buffer
    (insert content)
    (goto-char (point-min))
    (let ((summary nil))
      (while (re-search-forward "^## User (.*)$" nil t)
        (forward-line 1)
        (while (and (not (eobp))
                    (looking-at-p "^$"))
          (forward-line 1))
        (let ((body-start (point))
              (body-end (save-excursion
                          (if (re-search-forward "^## " nil t)
                              (match-beginning 0)
                            (point-max)))))
          (setq summary (buffer-substring-no-properties body-start body-end))
          (goto-char body-end)))
      (when summary
        (let ((collapsed (mdf/agent-shell--collapse-whitespace summary)))
          (unless (string-empty-p collapsed)
            (mdf/agent-shell--shorten-string collapsed 120)))))))

(defun mdf/agent-shell--transcript-search-key (content rowid)
  "Return a searchable string for CONTENT and ROWID."
  (let ((collapsed (mdf/agent-shell--collapse-whitespace content)))
    (format "%s [transcript:%s]"
            (if (string-empty-p collapsed) "" collapsed)
            rowid)))

(defun mdf/agent-shell--transcript-entry-display (summary agent session-id transcript-file rowid)
  "Format a consult display string for a transcript entry."
  (format "%s  [%s%s · %s · #%s]"
          (or summary "Transcript")
          (if (string-empty-p agent) "Unknown Agent" agent)
          (if (string-empty-p session-id)
              ""
            (format " · %s" session-id))
          (file-name-nondirectory transcript-file)
          rowid))

(defun mdf/agent-shell--read-transcript-entry ()
  "Prompt for a transcript entry using transcript contents."
  (require 'consult)
  (let* ((rows (mdf/agent-shell--sqlite-query
                "SELECT rowid, directory, COALESCE(session_id, ''), agent, transcript_link FROM agent_shell_transcripts ORDER BY rowid DESC"))
         (entries nil)
         (lookup (make-hash-table :test 'equal)))
    (dolist (row rows)
      (pcase-let ((`(,rowid ,directory ,session-id ,agent ,transcript-link)
                   (split-string row "\t")))
        (let* ((transcript-file (mdf/agent-shell--path-from-file-uri transcript-link)))
          (when (and transcript-file
                     (file-readable-p transcript-file))
            (let* ((content (mdf/agent-shell--transcript-file-contents transcript-file))
                   (summary (or (mdf/agent-shell--transcript-last-user-summary content)
                                (file-name-nondirectory transcript-file)))
                   (search-key (mdf/agent-shell--transcript-search-key content rowid))
                   (display (mdf/agent-shell--transcript-entry-display
                             summary agent session-id transcript-file rowid))
                   (entry (list :rowid rowid
                                :directory directory
                                :session-id session-id
                                :agent agent
                                :transcript-link transcript-link
                                :transcript-file transcript-file)))
              (push (propertize search-key 'display display) entries)
              (puthash search-key entry lookup))))))
    (unless entries
      (user-error "No transcript index entries found"))
    (let* ((choice (consult--read (nreverse entries)
                                  :prompt "Resume Cursor transcript (content search): "
                                  :sort nil
                                  :require-match t
                                  :category 'file
                                  :history 'file-name-history))
           (entry (gethash choice lookup)))
      (unless entry
        (user-error "Unknown transcript selection"))
      entry)))

(defun mdf/agent-shell-resume-cursor ()
  "Resume Cursor from a transcript index entry."
  (interactive)
  (unless (require 'agent-shell nil t)
    (user-error "agent-shell is not available"))
  (let* ((entry (mdf/agent-shell--read-transcript-entry))
         (directory (expand-file-name (plist-get entry :directory)))
         (session-id (string-trim (or (plist-get entry :session-id) "")))
         (agent-shell-preferred-agent-config 'cursor)
         (agent-shell-cwd-function (lambda () directory)))
    (unless (file-directory-p directory)
      (user-error "Transcript directory does not exist: %s" directory))
    (if (string-empty-p session-id)
        (agent-shell--new-shell :location directory)
      (agent-shell-resume-session session-id))))

[alberti42]

This is a lot of code. Can you mark it with triple fencing and a lisp like in

```lisp
your lisp code
```

Then it will look more readable, like in the example below taken from your code:

(defun mdf/agent-shell-resume-cursor ()
"Resume Cursor from a transcript index entry."
(interactive)
(unless (require 'agent-shell nil t)
(user-error "agent-shell is not available"))
(let* ((entry (mdf/agent-shell--read-transcript-entry))
(directory (expand-file-name (plist-get entry :directory)))
(session-id (string-trim (or (plist-get entry :session-id) "")))
(agent-shell-preferred-agent-config 'cursor)
(agent-shell-cwd-function (lambda () directory)))
(unless (file-directory-p directory)
(user-error "Transcript directory does not exist: %s" directory))
(if (string-empty-p session-id)
(agent-shell--new-shell :location directory)
(agent-shell-resume-session session-id))))

I love agent-shell and I even became a sponsor of @xenodium recently. However, I am still trying to figure out what the advantage is to running the agent shell in Emacs.

I recently wrote a package allowing perfect integration between tmux and Emacs https://github.com/alberti42/emacs-tmux-tandem that I have now been using daily for some weeks. The package is bug-free and functional; however, there may be breaking changes in the future as I am trying to figure out the best design to make the two great apps interact.

I don't buy into the narrative that everything needs to be done in Emacs. There are wonderful apps even outside of Emacs too.

I am now experimenting with a set of keystrokes that allow me to manage tmux windows and Emacs windows in the same way https://github.com/alberti42/emacs-config + https://github.com/alberti42/dotfiles. I would need to create a write-up where I present the recipe in a concise and scoped manner. But the bottom line is that I can merge, resize, move Emacs panes just with the same keys as with Tmux panes, and you would barely notice when you pass across the boundary of an Emacs pane to a Tmux pane.

In the Tmux panes, I can run any other TUI including Claude or Opencode, if I need it.

As I am relatively new to Emacs, I am genuinely interested to understand the advantages of, for example, handling the agents from inside Emacs.

[xenodium]

I love agent-shell and I even became a sponsor of @xenodium recently.

Thank you. Much appreciated.

However, I am still trying to figure out what the advantage is to running the agent shell in Emacs.

These days, I'm really enjoying the viewport interaction (setq agent-shell-prefer-viewport-interaction t). It feels fairly fluid to me, though I understand it may not be for everyone.

Check https://xenodium.com/agent-shell-0-47-1-updates#viewport-improvements and also https://xenodium.com/agent-shell-0-25-updates

Select a viewport region and pressing r can be handy to reply inline as if it was an email thread.

Pasting C-y with clipboard support enabled can be handy too. Take a screenshot of something, save it to clipboard, and paste into agent-shell to ask questions about it.

Image rendering is pretty neat. Specially when coupled with charting skills: https://xenodium.com/agent-shell-0-47-1-updates#image-rendering

Invoking M-x agent-shell in all sorts of contexts tries to do the right thing. Invoke it while viewing an image, and that image is sent to the last shell you accessed. Same for one or multiple marked dired files. Point on a flymake/flycheck error? M-x agent-shell sends the error too... There's more...

Many of these grew out desire for closer integration. Plenty more that can be done, of course.

ps. I try to document the features in blog posts. https://github.com/xenodium/agent-shell?tab=readme-ov-file#news