Skip to content

Design for the local v.s. remote CLI #4

Closed

Description

@simonw

In this PR I started work on integrating with local Claude Code JSONL files:

I need a confident design for how the CLI should support both web and local sessions, including sensible defaults.

Activity

  1. simonw commented on Dec 25, 2025

    @simonw
    OwnerAuthor

    First problem: what to call the remote sessions?

    The official Anthropic product name is "Claude Code on the web" but that's terrible - I use it in their native iPhone app and the Claude Desktop app, I hardly ever interact with it in a web browser.

    Also using --web as an option in my tool is confusing because my tool is all about creating HTML versions of transcripts that can be published to the web.

    Some options for language:

    • "local" v.s. "remote"
    • "local" v.s. "cloud"
    • "local" v.s. "asynchronous" or "async"

    I'm pretty set on "local" for the one option.

  2. simonw commented on Dec 25, 2025

    @simonw
    OwnerAuthor

    Polled Twitter for some thoughts: https://x.com/simonw/status/2004214474878947667

    Decision: I'm going to use cloud.

  3. simonw commented on Dec 25, 2025

    @simonw
    OwnerAuthor

    OK, so I think:

    claude-code-publish
    

    With no options shows a list of local conversations for you to select.

    claude-code-publish cloud
    

    Shows a list of cloud conversations.

    Then assuming you already have a path to some JSON (in either format since we can distinguish the two):

    claude-code-publish path-to-JSON
    

    That works for paths, but lets allow it to work for cloude session IDs too (again, easy to distinguish):

    claude-code-publish session_1234
    

    Most commands take the --json and --gist and --open options.

  4. simonw commented on Dec 25, 2025

    @simonw
    OwnerAuthor

    I think I need to rename the tool to claude-code-transcripts because actually the --open feature is incredibly useful independent of publishing.

    Also add a -r/--recent option to open the most recent local transcript in your browser.

  5. simonw commented on Dec 25, 2025

    @simonw
    OwnerAuthor

    So maybe:

    claude-code-transcripts
    

    Shows a list of local transcripts and when you select one it exports to /tmp and opens in your browser.

    And this doesn't even let you select, it just does the most recent one:

    claude-code-transcripts -r
    
  6. simonw commented on Dec 25, 2025

    @simonw
    OwnerAuthor

    Changed my mind, I'm going to go with web - it's a bad name but it's the official name, and if Anthropic change it to something more sensible in the future I can update this app to match.

  7. simonw commented on Dec 25, 2025

    @simonw
    OwnerAuthor

    So in that case, to list remote transcript do:

    claude-code-transcripts web
    

    And actually, since the case where you are dealing directly with JSON files (of either format) is pretty rare, I'm going to move those to a sub-command of their own:

    claude-code-transcripts json path-to-JSON
    
  8. simonw commented on Dec 25, 2025

    @simonw
    OwnerAuthor

    Then claude-code-transcripts with no arguments can be the default alias for claude-code-transcripts local.

    So now we have three potential sources of transcript information:

    claude-code-transcripts local # you pick from a list of local ones
    claude-code-transcripts web # you pick from list of web sessions
    claude-code-transcripts json PATH # you provide a path to JSON
    

    All of these can support --gist and --json (for include JSON) and --open and -o path-to-output including -o . for current folder.

  9. simonw commented on Dec 25, 2025

    @simonw
    OwnerAuthor

    I mused with Claude Code local a bit, here's the transcript (generated using the new local JSONL support from #3): https://gistpreview.github.io/?2cf63cf05e6703527724b324b7e813fd/index.html

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions