> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runaether.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Record that a folder's next terminal chat is a fork of a chat

> Records the caller's word that the next terminal chat created in a folder of their computer is a fork of one of their Aether chats: when the machine bridge first mirrors a Claude Code session of that folder's work tree, its chat names the Aether chat as the chat it was forked from. Answers 201 with the pending fork and when it expires.

Use this tool when you need to:
- Link the chat Claude Code forks on your computer to the Aether chat it continues, as `aether task chats continue` does before it prints the resume command

Examples:
- POST /computers/{computerID}/pending-terminal-forks {"task_id": "5b0c1f8e-2a4d-4c3b-9e7f-1d2a3b4c5d6e", "chat_id": "8d7e6f5a-4b3c-4d2e-9f1a-0b9c8d7e6f5a", "folder": "/Users/ada/src/aether-fix-login"}

Hints:
- folder is the work tree's folder as the machine bridge reports it: the top of the git checkout, its path resolved (/private/tmp, not /tmp, on macOS).
- The fork is taken once: by the first terminal chat created in a work tree of that folder, and only one of the caller's. It expires 24 hours after it is recorded, and a terminal chat created after that is no fork. Recording again for the same folder replaces it.
- The lineage comes from this record alone, never from the session file, which names no source once Claude Code forks it.
- Only the task's creator records a fork of its chats, while they can read the task in its organization: a task they cannot read or did not create answers 404 not_found, as does a computer that is not theirs or a chat that is no Aether chat of the task.
- Only the grant of the caller's coding agent's bridge on the computer calls it, as `aether task chats continue` does: a session or an API key is refused with 403 credential_kind_not_admitted.
- The call presents the computer's own secret, which aether setup keeps on it, in the Aether-Computer-Secret header. A computer that has none is refused with 403 computer_needs_setup: update the aether CLI there and run aether setup. A call that presents no secret, or another, is refused with 403 computer_set_up_elsewhere.



## OpenAPI

````yaml api-reference/openapi.json POST /computers/{computerID}/pending-terminal-forks
openapi: 3.1.0
info:
  title: Aether API
  version: 0.1.0
servers:
  - url: https://api.runaether.dev
security:
  - bearerAuth: []
paths:
  /computers/{computerID}/pending-terminal-forks:
    post:
      tags:
        - computers
      summary: Record that a folder's next terminal chat is a fork of a chat
      description: >-
        Records the caller's word that the next terminal chat created in a
        folder of their computer is a fork of one of their Aether chats: when
        the machine bridge first mirrors a Claude Code session of that folder's
        work tree, its chat names the Aether chat as the chat it was forked
        from. Answers 201 with the pending fork and when it expires.


        Use this tool when you need to:

        - Link the chat Claude Code forks on your computer to the Aether chat it
        continues, as `aether task chats continue` does before it prints the
        resume command


        Examples:

        - POST /computers/{computerID}/pending-terminal-forks {"task_id":
        "5b0c1f8e-2a4d-4c3b-9e7f-1d2a3b4c5d6e", "chat_id":
        "8d7e6f5a-4b3c-4d2e-9f1a-0b9c8d7e6f5a", "folder":
        "/Users/ada/src/aether-fix-login"}


        Hints:

        - folder is the work tree's folder as the machine bridge reports it: the
        top of the git checkout, its path resolved (/private/tmp, not /tmp, on
        macOS).

        - The fork is taken once: by the first terminal chat created in a work
        tree of that folder, and only one of the caller's. It expires 24 hours
        after it is recorded, and a terminal chat created after that is no fork.
        Recording again for the same folder replaces it.

        - The lineage comes from this record alone, never from the session file,
        which names no source once Claude Code forks it.

        - Only the task's creator records a fork of its chats, while they can
        read the task in its organization: a task they cannot read or did not
        create answers 404 not_found, as does a computer that is not theirs or a
        chat that is no Aether chat of the task.

        - Only the grant of the caller's coding agent's bridge on the computer
        calls it, as `aether task chats continue` does: a session or an API key
        is refused with 403 credential_kind_not_admitted.

        - The call presents the computer's own secret, which aether setup keeps
        on it, in the Aether-Computer-Secret header. A computer that has none is
        refused with 403 computer_needs_setup: update the aether CLI there and
        run aether setup. A call that presents no secret, or another, is refused
        with 403 computer_set_up_elsewhere.
      operationId: createPendingTerminalFork
      parameters:
        - in: path
          name: computerID
          required: true
          schema:
            format: uuid
            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
            type: string
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                chat_id:
                  description: The Aether chat the terminal chat is forked from.
                  format: uuid
                  type: string
                folder:
                  description: >-
                    The work tree's folder on the computer, as the machine
                    bridge reports it: the top of the git checkout, its path
                    resolved.
                  maxLength: 4096
                  minLength: 1
                  pattern: ^/
                  type: string
                  x-aether-string-length-unit: unicode-code-point
                task_id:
                  description: The task of the chat the terminal chat is forked from.
                  format: uuid
                  type: string
              required:
                - task_id
                - chat_id
                - folder
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PendingTerminalFork'
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComputersErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/ComputersErrorResponse'
                  - $ref: '#/components/schemas/OrgAuthorizationErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComputersErrorResponse'
          description: Not Found
        '410':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComputersErrorResponse'
          description: Gone
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComputersErrorResponse'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComputersErrorResponse'
          description: Internal Server Error
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComputersErrorResponse'
          description: Service Unavailable
components:
  schemas:
    PendingTerminalFork:
      additionalProperties: false
      properties:
        chat_id:
          format: uuid
          type: string
        expires_at:
          description: >-
            When the pending fork lapses: a terminal chat created in the folder
            after it is no fork.
          format: date-time
          type: string
        folder:
          maxLength: 4096
          minLength: 1
          pattern: ^/
          type: string
          x-aether-string-length-unit: unicode-code-point
        task_id:
          format: uuid
          type: string
      required:
        - task_id
        - chat_id
        - folder
        - expires_at
      type: object
    ComputersErrorResponse:
      additionalProperties: false
      properties:
        code:
          enum:
            - account_deleting
            - aether_inference_unserved
            - agent_pr_blocked
            - agent_pr_pending
            - agent_profile_changed
            - agent_starts_off
            - agent_starts_on_from_computer_only
            - agent_uses_own_sign_in
            - answer_on_its_way
            - app_identity_missing
            - attachments_unsupported
            - attribution_unavailable
            - bad_gateway
            - bad_request
            - base_branch_unusable
            - branch_exists
            - caller_inactive
            - chat_archived
            - chat_being_forked
            - chat_moved
            - chat_not_removable
            - chat_settings_fixed
            - chats_not_addable
            - checkout_not_archivable
            - cli_upgrade_required
            - client_outdated
            - computer_cli_outdated
            - computer_needs_fresh_sign_in
            - computer_needs_setup
            - computer_registered_to_another_person
            - computer_set_up_elsewhere
            - computer_starts_no_agents
            - computer_starts_no_forks
            - computer_task_start_moved
            - computer_unreachable
            - conflict
            - connection_creator_only
            - connection_harness_mismatch
            - connection_not_held
            - contents_write_required
            - continuation_failed
            - continuation_unavailable
            - control_forbidden
            - credential_kind_not_admitted
            - credential_named_file
            - detached_head
            - download_unsupported
            - embeddings_unavailable
            - feature_unsupported
            - file_references_unsupported
            - fix_not_requested
            - fix_requests_unrecorded
            - forbidden
            - fork_branch_delete_unsupported
            - fork_forbidden
            - fork_in_progress
            - fork_unsupported
            - gateway_timeout
            - github_failed
            - github_identity_required
            - github_push_access_required
            - gone
            - handed_branch_protected
            - head_moved
            - html_render_nul_byte
            - html_render_too_large
            - idempotency_key_conflict
            - idempotency_key_reused
            - idle_compaction_not_pending
            - idle_compaction_skipped
            - inference_proxy_unavailable
            - insufficient_credits
            - insufficient_inference_balance
            - interaction_mode_unsupported
            - internal_error
            - invalid_request
            - last_queued_message
            - live_protocol_unsupported
            - main_chat_permanent
            - mcp_server_not_connected
            - merge_when_ready_requires_pr_review
            - message_not_queued
            - message_not_waiting
            - method_not_allowed
            - mode_forbidden
            - name_follows_session
            - no_checkout_on_computer
            - no_checkpoint_yet
            - no_commit
            - no_dispatch_target
            - no_main_chat
            - no_origin
            - no_work_tree_folder
            - not_acceptable
            - not_found
            - not_implemented
            - onboarding_already_completed
            - onboarding_requirements_missing
            - open_in_terminal
            - org_id_required
            - org_role_insufficient
            - org_suspended
            - payment_required
            - pending_input_answered
            - permission_prompt_open
            - pr_automation_unsupported
            - pr_review_actor_required
            - pr_review_connection_spent
            - pr_review_publish_forbidden
            - precondition_failed
            - project_has_no_repository
            - project_not_a_choice
            - project_required
            - prompt_decisions_refused
            - pull_request_closed
            - pull_request_mirror_failed
            - pull_request_not_mirrored
            - push_failed
            - question_answers
            - question_shortened
            - queue_for_later_unsupported
            - queued_stop_requires_discard
            - rate_limited
            - reasoning_effort_fixed
            - remote_changes_on_from_computer_only
            - repository_not_connected
            - request_canceled
            - request_expired
            - request_timeout
            - request_too_large
            - review_name_follows_pull_request
            - sandbox_deleted
            - sandbox_failed
            - sandbox_needs_message
            - service_unavailable
            - session_file_generation
            - session_file_hole
            - session_file_missing
            - session_file_range_differs
            - session_gone
            - session_not_started_by_aether
            - slash_commands_unsupported
            - stack_cycle
            - stack_too_large
            - stack_two_parents
            - stale_execution
            - stale_or_indeterminate
            - stale_pending_input
            - start_cancelled
            - stream_delivery_gap
            - stream_event_conflict
            - task_archived
            - task_awaiting_message
            - task_awaiting_tool_response
            - task_backed_by_work_tree
            - task_connection_disconnected
            - task_creator_deleted
            - task_has_no_branch
            - task_has_no_repository
            - task_ineligible
            - task_not_accepting_messages
            - task_not_pinnable
            - task_not_started
            - task_settings_changed
            - task_start_failed
            - task_start_pending
            - teleport_unavailable
            - terminal_chat
            - terminal_chat_continuation_refused
            - terminal_chat_prompt_closed_otherwise
            - terminal_chat_prompt_differs
            - terminal_chat_prompt_not_answered
            - terminal_chat_removed
            - terminal_chat_run_moved
            - terminal_question
            - too_large
            - too_many_live_connections
            - too_many_waiting_messages
            - turn_running
            - unauthenticated
            - unsigned_aether_head
            - unsigned_commit
            - unsupported_changes
            - unsupported_media_type
            - untyped_error
            - user_suspended
            - validation_failed
            - work_tree_repository_differs
            - workspace_git_unavailable
            - workspace_gone
            - workspace_outdated
            - workspace_rejected
            - workspace_start_failed
          minLength: 1
          type: string
        error:
          minLength: 1
          type: string
        errors:
          items:
            $ref: '#/components/schemas/ErrorDetail'
          type: array
      required:
        - error
        - code
      type: object
    OrgAuthorizationErrorResponse:
      additionalProperties: false
      properties:
        code:
          enum:
            - org_membership_required
            - org_role_insufficient
            - org_suspended
            - account_deleting
            - agent_host_route_not_allowed
            - credential_kind_not_admitted
            - grant_scope_insufficient
          type: string
        error:
          minLength: 1
          type: string
      required:
        - error
        - code
      type: object
    ErrorDetail:
      additionalProperties: false
      properties:
        location:
          description: >-
            Where the error occurred, e.g. 'body.items[3].tags' or
            'path.thing-id'
          type: string
        message:
          description: Error message text
          type: string
        value:
          description: The value at the given location
      type: object
  securitySchemes:
    bearerAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.